Update wording to be clear and concise

Author: brunopgalvao

.CONTRIBUTING.md

@@ -57,13 +57,17 @@ Before making contributions, you need to set up the proper directory structure f
 
 1. **Clone the MkDocs repository**
 
+   > **polkadot-mkdocs**: Contains the "engine" (MkDocs configuration, theme, styling)
+
    ```bash
    git clone https://github.com/papermoonio/polkadot-mkdocs
    cd polkadot-mkdocs
    ```
 
 2. **Fork and clone the docs repository inside polkadot-mkdocs**
 
+   > **polkadot-docs**: Contains the "content" (documentation pages, tutorials, images)
+
    ```bash
    # Fork polkadot-docs on GitHub first, then:
    git clone https://github.com/your-username/polkadot-docs.git

.github/pull_request_template.md

@@ -8,13 +8,13 @@ Choose one:
 - [ ] ✅ I have time to handle formatting/style feedback myself 
 - [ ] ⚡ Docs team handles formatting (check "Allow edits from maintainers")  
 
-## 🤖 AI Docs
+## 🤖 AI-Ready Docs
 
-If content changed, regenerate AI files:
+If content changed, [regenerate AI files](../CONTRIBUTING.md#making-changes):
 - [ ] ✅ I ran `python3 scripts/generate_llms.py`  
 - [ ] ⚡ Docs team will regenerate (check "Allow edits from maintainers")  
 
 ## ✅ Checklist
 
 - [ ] Changes tested  
-- [ ] [PaperMoon Style Guide](https://github.com/papermoonio/documentation-style-guide) followed  
+- [ ] [PaperMoon Style Guide](https://github.com/papermoonio/documentation-style-guide) followed

README.md

@@ -12,9 +12,9 @@ Follow these steps to run the documentation site locally and preview your change
 
 Building and serving the site requires cloning two repositories:
 
-- **[Polkadot MkDocs](https://github.com/papermoonio/polkadot-mkdocs)**: Contains the MkDocs configuration files, theme overrides, and custom CSS for the Polkadot documentation site.
+- **[Polkadot MkDocs](https://github.com/papermoonio/polkadot-mkdocs)**: Contains the "engine" (MkDocs configuration, theme overrides, and custom CSS) for the Polkadot documentation site.
 
-- **[Polkadot Docs](https://github.com/polkadot-developers/polkadot-docs)**: The actual content is stored in the `polkadot-docs` repository and pulled into the `polkadot-mkdocs` directory during build.
+- **[Polkadot Docs](https://github.com/polkadot-developers/polkadot-docs)**: Contains the "content" (documentation pages, tutorials, and images) that gets built into the site.
 
 For everything to work correctly, the file structure needs to be as follows:
 
@@ -71,23 +71,14 @@ pip install -r requirements.txt
 
 After a successful build, the site should be available at http://127.0.0.1:8000.
 
-### Deactivating the Virtual Environment
+### Working with the Docs
 
-When you're done working on the documentation, you can deactivate the virtual environment by running:
+When you're done working, run `deactivate` to exit the virtual environment.
 
-```bash
-deactivate
-```
-
-### Next Time You Work on the Docs
-
-When you return to work on the documentation:
-
-1. Navigate to the `polkadot-mkdocs` directory
-2. Activate the virtual environment:
-   - macOS/Linux: `source venv/bin/activate`
-   - Windows: `venv\Scripts\activate`
-3. Run `mkdocs serve` to start the development server
+To work on the docs again:
+1. Navigate to `polkadot-mkdocs` 
+2. Activate the environment: `source venv/bin/activate` (Windows: `venv\Scripts\activate`)
+3. Run `mkdocs serve`
 
 ## Contributing