Update workflow

Author: brunopgalvao

.CONTRIBUTING.md

@@ -5,31 +5,88 @@
 ## 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)
+- [Edit Online with GitHub (Simple Changes)](#edit-online-with-github-simple-changes)
+- [Fork and Edit Locally](#fork-and-edit-locally)
+   - [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**
+There are two main ways to contribute:
+
+- **[Edit Online with GitHub](#edit-online-with-github-simple-changes)** 
+   - Best for simple text changes like fixing typos or making small updates directly in your browser.  
+
+- **[Fork and Edit Locally](#fork-and-edit-locally)** 
+   - Recommended for more complex contributions that require local testing or previewing changes.
+
+
+## Edit Online with GitHub (Simple Changes)
+
+For simple contributions like fixing typos or making small text changes, you can use GitHub's online editor:
+
+### Making Your Changes
+
+1. **Navigate to the file** you want to edit on GitHub
+2. **Click the pencil icon** (✏️) to edit the file
+3. **Make your changes** in the online editor
+4. **Follow the style guide** - ensure your changes follow the [PaperMoon Style Guide](https://github.com/papermoonio/documentation-style-guide)
+
+### Creating Your Pull Request
+
+1. **Scroll to "Propose changes"** at the bottom of the editor
+2. **Add a descriptive commit message** explaining your changes
+3. **Click "Propose changes"** - GitHub will automatically:
+   - Fork the repository to your account
+   - Create a branch with your changes
+   - Open a pull request
+
+## Fork and Edit Locally
+
+For more complex contributions which involve rendering (e.g. adding a `.Nav` section, code snippets, etc) or when you want to preview changes locally, follow these steps:
+
+### Initial Setup
+
+Before making contributions, you need to set up the proper directory structure for local development:
+
+1. **Clone the MkDocs repository**
 
    ```bash
+   git clone https://github.com/papermoonio/polkadot-mkdocs
+   cd polkadot-mkdocs
+   ```
+
+2. **Fork and clone the docs repository inside polkadot-mkdocs**
+
+   ```bash
+   # Fork polkadot-docs on GitHub first, then:
    git clone https://github.com/your-username/polkadot-docs.git
    cd polkadot-docs
    git checkout -b your-feature-branch
    ```
 
-2. **Make Your Changes**
+   Your directory structure should now look like:
+   ```
+   polkadot-mkdocs/
+   ├── polkadot-docs/          # Your forked repository
+   ├── material-overrides/
+   └── mkdocs.yml
+   ```
+
+### Making Changes
+
+1. **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))
+   - Test your changes locally (see [Run Polkadot Docs Locally](../README.md#run-polkadot-docs-locally))
 
-3. **Update AI Documentation**
+2. **Update AI Documentation**
 
    After making content changes, regenerate the AI-ready documentation files. 
 
@@ -39,7 +96,7 @@
    ```
    **Note**: Run this script on every PR once all changes are committed.
 
-4. **Create Pull Request**
+3. **Create Pull Request**
 
    - Push your branch and create a pull request
    - Use the PR template to indicate your review preference
@@ -73,9 +130,11 @@ To add a page to an existing section:
    # Page Title
 
    ## Introduction
+
    Write 2-3 paragraphs to introduce the topic.
 
    ## Prerequisites
+
    List any required tools, knowledge, or setup.
    ```
 
@@ -156,21 +215,30 @@ 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 Categories
+
+Available categories for tutorials are found in [scripts/llms_config.json](./scripts/llms_config.json).
+
 ### Tutorial Requirements
 
 - All code examples must be tested and functional

.github/pull_request_template.md

@@ -1,23 +1,20 @@
-## Description
+## 📝 Description
 
 Provide a clear and concise description of your changes.
 
-## Review Process Preference
+## 🔍 Review Preference
 
-Select your preference for the review process:
+Choose one:
+- [ ] ✅ I have time to handle formatting/style feedback myself 
+- [ ] ⚡ Docs team handles formatting (check "Allow edits from maintainers")  
 
-- [ ] I have time to handle formatting and style review feedback myself
-- [ ] Please have the Polkadot Docs team take over for formatting review to expedite the process (you must also check "Allow edits from maintainers" at the bottom of this page)
+## 🤖 AI Docs
 
-## Checklist
+If content changed, regenerate AI files:
+- [ ] ✅ I ran `python3 scripts/generate_llms.py`  
+- [ ] ⚡ Docs team will regenerate (check "Allow edits from maintainers")  
 
-Before submitting this PR, please verify:
+## ✅ Checklist
 
-- [ ] I have tested my changes locally
-- [ ] I have followed the [PaperMoon Documentation Style Guide](https://github.com/papermoonio/documentation-style-guide) (required)
-- [ ] I have run `python3 scripts/generate_llms.py` to update AI documentation files (if applicable)
-
-**For content with images:**
-
-- [ ] Images are in `.webp` format
-- [ ] Images follow size requirements (1512px width for desktop screenshots, 400x600px for browser extensions)
+- [ ] Changes tested  
+- [ ] [PaperMoon Style Guide](https://github.com/papermoonio/documentation-style-guide) followed  

README.md

@@ -39,6 +39,10 @@ To set up the structure, follow these steps:
     cd polkadot-mkdocs
     git clone https://github.com/polkadot-developers/polkadot-docs.git
     ```
+    > **📋 Contributing?** If you plan to [contribute](./CONTRIBUTING.md) to the documentation, fork the `polkadot-docs` repository first and clone your fork instead:
+    > ```bash
+    > git clone https://github.com/your-username/polkadot-docs.git
+    > ```
 
 ### Set Up Python Environment