Improve CONTRIBUTING workflow

Author: brunopgalvao

.CONTRIBUTING.md

@@ -0,0 +1,218 @@
+# Contribute to the Polkadot Docs
+
+> **📋 Essential**: All contributions must follow the [PaperMoon Style Guide](https://github.com/papermoonio/documentation-style-guide).
+
+## Contents
+- [Quick Start](#quick-start)
+- [Fix or Improve Existing Content](#fix-or-improve-existing-content)
+- [Add a New Page](#add-a-new-page)
+- [Create a New Section](#create-a-new-section)
+- [Write a Tutorial](#write-a-tutorial)
+- [Working with Content Elements](#working-with-content-elements)
+  - [Adding Images](#adding-images)
+  - [Using Code Snippets](#using-code-snippets)
+  - [Adding Callout Boxes](#adding-callout-boxes)
+
+## Quick Start
+
+1. **Fork and Create Branch**
+   ```bash
+   git clone https://github.com/your-username/polkadot-docs.git
+   cd polkadot-docs
+   git checkout -b your-feature-branch
+   ```
+
+2. **Make Your Changes**
+   - Follow the [PaperMoon Style Guide](https://github.com/papermoonio/documentation-style-guide)
+   - Test your changes locally (see [Running Polkadot Docs Locally](../README.md#run-polkadot-docs-locally))
+
+3. **Update AI Documentation**
+   After making content changes, regenerate the AI-ready documentation files:
+   ```bash
+   python3 scripts/generate_llms.py
+   ```
+   **Note**: Run this script on every PR once all changes are committed.
+
+4. **Create Pull Request**
+   - Push your branch and create a pull request
+   - Use the PR template to indicate your review preference
+
+## Fix or Improve Existing Content
+
+Making changes to existing pages is the simplest contribution:
+
+1. **Edit the content** - Make your improvements directly to the existing markdown file
+2. **Follow page requirements** - Ensure your changes maintain proper formatting
+3. **Test locally** - Verify your changes render correctly
+
+**No additional files need updating** when you're only modifying existing content.
+
+## Add a New Page
+
+**Requirement**: Follow the [PaperMoon Documentation Style Guide](https://github.com/papermoonio/documentation-style-guide).
+
+To add a page to an existing section:
+
+1. **Create your markdown file** following [naming conventions](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md#naming-conventions)
+
+2. **Include required frontmatter**:
+   ```markdown
+   ---
+   title: Page Title (max 60 chars for SEO)
+   description: Description for SEO (120-160 chars)
+   ---
+   
+   # Page Title
+   
+   ## Introduction
+   Write 2-3 paragraphs to introduce the topic.
+   
+   ## Prerequisites
+   List any required tools, knowledge, or setup.
+   ```
+
+   Resources for good SEO:
+   - [Google's title recommendations](https://developers.google.com/search/docs/advanced/appearance/title-link?hl=en)
+   - [Google's description recommendations](https://developers.google.com/search/docs/advanced/appearance/snippet?hl=en)
+
+3. **Update navigation** - Add your page to the `.nav.yml` file in the same directory:
+   ```yaml
+   - 'Your Page Display Name': 'your-file-name.md'
+   ```
+
+## Create a New Section
+
+To create an entirely new section of documentation:
+
+1. **Create directory structure**:
+   ```
+   your-new-section/
+   ├── .nav.yml
+   ├── index.md
+   └── your-first-page.md
+   ```
+
+2. **Create `.nav.yml`**:
+   ```yaml
+   title: Section Display Name
+   nav: 
+     - index.md
+     - 'Page Display Name': 'file-name.md'
+     - subdirectory-name
+   ```
+   
+   - `title`: Displayed in left navigation
+   - `index.md`: Always first in nav list
+   - Files: `'Display Name': 'file-name.md'`
+   - Subdirectories: Listed by directory name
+
+3. **Create `index.md`** - Landing page with frontmatter and content introducing the section
+
+## Write a Tutorial
+
+This section covers tutorial-specific requirements and formatting.
+
+**Requirement**: Follow the [PaperMoon Documentation Style Guide](https://github.com/papermoonio/documentation-style-guide).
+
+### Choose Your Tutorial Section
+```
+tutorials/
+├── dapps/              # Application development guides
+├── interoperability/   # XCM, cross-chain operations
+├── onchain-governance/ # Governance operations
+├── polkadot-sdk/      # SDK-based development
+└── smart-contracts/    # Smart contract development
+```
+
+### Set Up Directory Structure
+```
+tutorials/[section]/[subsection]/[tutorial-name].md
+images/tutorials/[section]/[subsection]/[tutorial-name]/
+.snippets/code/tutorials/[section]/[subsection]/[tutorial-name]/
+```
+
+### Use the Tutorial Template
+```markdown
+---
+title: Tutorial Title (max 60 chars)
+description: Description 120-160 chars
+tutorial_badge: Beginner | Intermediate | Advanced
+categories: Category1, Category2
+---
+
+# Tutorial Title
+
+## Introduction
+Brief explanation of what users will learn/build
+
+## Prerequisites
+Required knowledge/tools
+
+## [Action-Oriented Section Title]
+Instructions with commands
+
+## Verification
+How to confirm it worked
+
+## Where to Go Next
+Related tutorials
+```
+
+### Tutorial Requirements
+- All code examples must be tested and functional
+- Always specify dependency versions (e.g., `npm install [email protected]`)
+- Use action-oriented section titles
+- Include verification steps
+
+## Working with Content Elements
+
+### Adding Images
+
+**Where to store**: `images/<path-matching-doc-structure>/`
+
+**Requirements**:
+- Format: `.webp`
+- Desktop screenshots: 1512px width, variable height
+- Browser extension screenshots: 400x600px
+
+**How to use**:
+```markdown
+![Alt text description](/docs/images/<subdirectory>/<image-file-name>.webp)
+```
+
+**Adding annotations**:
+Use assets from [.assets/annotations](.assets/annotations/) directory:
+- **Arrows**: Highlight single elements
+- **Steps**: Highlight multiple elements (use numbers for numbered lists, letters for alphabetical lists)
+
+### Using Code Snippets
+
+**Purpose**: For any code used on the page or for reuse of text across multiple pages while maintaining it in one place
+
+**Where to store**: `.snippets/code/<path-matching-doc-structure>/<snippet-name>`
+
+**How to use**:
+```javascript
+--8<-- 'code/<subdirectory>/<snippet-file-name>.js:10:20'
+```
+
+**File types**:
+- **Text snippets**: `.md` files for reusable copy
+- **Code snippets**: Use appropriate language extension (`.js`, `.py`, etc.)
+
+Learn more about [snippets syntax](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/).
+
+### Adding Callout Boxes
+
+Use these to highlight important information:
+
+```markdown
+!!!tip
+    Helpful tips and shortcuts
+
+!!!note
+    Important information to remember
+
+!!!warning
+    Potential issues or caveats
+```