add assets for external contributors and update contributing docs (#929)

* add assets for external contributors and update contributing docs

* Update .CONTRIBUTING/.CONTRIBUTING.md

Co-authored-by: Copilot <[email protected]>

* ignore the contributing directory

* update text color to white

---------

Co-authored-by: Copilot <[email protected]>

Author: eshaben

.CONTRIBUTING.md .CONTRIBUTING/.CONTRIBUTING.md.CONTRIBUTING.md renamed to .CONTRIBUTING/.CONTRIBUTING.md

@@ -13,14 +13,14 @@ This guide covers how to contribute to the documentation, including serving a lo
     - [Install Dependencies and Serve Site](#install-dependencies-and-serve-site)
   - [Adding New Pages](#adding-new-pages)
     - [Creating a New Section](#creating-a-new-section)
-      - [Example `.pages` File](#example-pages-file)
+      - [Example `.nav.yml` File](#example-navyml-file)
       - [Example `index.md` File](#example-indexmd-file)
     - [Adding Pages to Existing Section](#adding-pages-to-existing-section)
   - [Modifying Existing Pages](#modifying-existing-pages)
   - [Adding Code and Text Snippets](#adding-code-and-text-snippets)
   - [Adding Images](#adding-images)
+    - [Image Annotations](#image-annotations)
   - [Search Engine Optimization (SEO)](#search-engine-optimization-seo)
-  - [Tools for Editing](#tools-for-editing)
 
 ## Viewing Site Locally
 
@@ -90,16 +90,16 @@ When adding new pages to the documentation site, it is important to ensure all r
 
 To create a new section of pages, you will first need to create a subdirectory with the desired name of the section. The root directory, and every subdirectory, must contain the following files:
 
-- **`.pages`**: Defines the structure of the documentation site.
+- **`.nav.yml`**: Defines the structure of the documentation site.
 - **`index.md`**: A landing page which can be used to provide more context about the content in the section.
 
-#### Example `.pages` File
+#### Example `.nav.yml` File
 
 ```markdown
 title: Application Developers
 nav: 
   - index.md
-  - **'Polkadot SDK'**: 'polkadot-sdk.md'
+  - 'Polkadot SDK': 'polkadot-sdk.md'
   - interact
   - tooling
 ```
@@ -138,10 +138,9 @@ If you are adding pages to an existing section, the steps are simplified. Howeve
     - **`title`**: Represents the `<title>` tag and is used for SEO purposes (not displayed on the published site) Titles have a maximum length of 45 characters.
     - **`description`**: Represents the meta-description and is also used for SEO purposes (not displayed on the published site). Descriptions should be 120-160 characters and should provide a preview into the page topic.
     - **Page title**: An H1 heading title to be displayed at the top of the page.
-
     - **`## Checking Prerequisites` section**: If the guide requires the user to have specific developer tools installed, for example, Docker or MetaMask, it should be listed here.
 
-- **Add the 'Display Name'**: 'file-name.md' for the new page to the `.pages` folder in the same subdirectory where you added the new page.
+- **Add the 'Display Name'**: 'file-name.md' for the new page to the `.nav.yml` file in the same subdirectory where you added the new page.
 
 An example new content page might look like:
 
@@ -177,7 +176,7 @@ More resources for [SEO Optimization](#search-engine-optimization-seo) of titles
 3. Once you commit and push all of your changes, open a pull request for the new content branch against the `main` branch.
 4. Monitor notifications and pull requests for feedback from code owners. At least one approval is required before merging content.
 
-If your additions or modifications are limited to content on an existing page, there is no need to worry about the [`.pages`](#example-pages-file) or [`index.md`](#example-indexmd-file) files, as changes to page content don't affect these files.
+If your additions or modifications are limited to content on an existing page, there is no need to worry about the [`.nav.yml`](#example-navyml-file) or [`index.md`](#example-indexmd-file) files, as changes to page content don't affect these files.
 
 ## Adding Code and Text Snippets
 
@@ -197,48 +196,40 @@ Learn more about the effective use of [snippets](https://facelessuser.github.io/
 
 ## Adding Images
 
-Images are stored in the `images` subdirectory. They are organized to mirror the structure of the docs site. For example, to add an image to the page `/develop/application-devs/tooling/chopsticks/overview.md`, you would place the image in the folder `images/application-devs/tooling/chopsticks/overview`
+- Store images in the `images` subdirectory, mirroring the docs site structure.
 
-All images intended for display on the website should be in `.webp` format. You can look up an image converter online to convert from `.jpeg`, `.png`, or other formats to `.webp`.
+    - **Example**: an image on the page `/develop/application-devs/tooling/chopsticks/overview.md` goes in the `images/application-devs/tooling/chopsticks/overview` folder.
 
-To add an image to your page, you should have [alt text](https://developers.google.com/style/images#alt-text) and use the following syntax:
+- Use `.webp` format. You can look up an image converter online to convert from `.jpeg`, `.png`, or other formats to `.webp`.
+- Add [alt text](https://developers.google.com/style/images#alt-text) using the following syntax:
 
-```markdown
-![Alt text goes here](/docs/images/<subdirectory>/<image-file-name>.webp)
-```
+    ```markdown
+    ![Alt text goes here](/docs/images/<subdirectory>/<image-file-name>.webp)
+    ```
 
 See the [style guide](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md#screenshots) for more tips on handling images.
 
-## Search Engine Optimization (SEO)
-
-Here are some resources to help you create good titles and descriptions for SEO:
+### Image Annotations
 
-- [Google's recommendation on good titles](https://developers.google.com/search/docs/advanced/appearance/title-link?hl=en)
-- [Google's recommendation on good descriptions](https://developers.google.com/search/docs/advanced/appearance/snippet?hl=en)
+To annotate images, you can use the provided assets for arrows and steps. These are located in the [.CONTRIBUTING/image-assets](./image-assets/) directory, which contains SVGs you can overlay on images.
 
-In general, titles should be between 50 and 60 characters and descriptions should be between 120 and 160 characters.
+- **Arrows**: Highlight a single important aspect.
 
-## Tools for Editing
+    ✅ Use arrows to highlight one key element.
 
-There are a few tools you may find useful for proofreading and editing your contributions:
+    ❌ Do not use arrows if multiple elements need highlighting, use steps instead.
 
-- **[Vale](https://vale.sh/)**: The `polkadot-mkdocs` repository contains configuration for Vale, an open source NLP-powered linter for text. The configuration is a work in progress with a growing custom dictionary tailored toward software engineering, blockchain, and Polkadot terms. Running Vale against your files locally can serve as a first round of feedback to speed up the review process.
+- **Steps**: Highlight multiple actions or elements. If the page shows a numbered list (1, 2, 3...), then use numeric steps (1–9) in the image. If the page shows an alphabetical list (a, b, c...), then use lettered steps (a–i) in the image.
 
-To use Vale locally to screen your work:
+    ✅ Use steps to show several steps on a page.
 
-1. Visit the Vale site and follow the [installation instructions](https://vale.sh/docs/vale-cli/installation/).
-2. From the `polkadot-mkdocs` directory, run the following in your terminal:
+    ❌ Do not use steps if there is only one thing to highlight, use an arrow instead.
 
-    ```bash
-    vale INSERT_PATH_TO_FILE
-    ```
-
-    The output will look something like:
-
-    ![Vale sample terminal output](images/contributing/vale-output-01.webp)
+## Search Engine Optimization (SEO)
 
-3. You can use CMD+click to open the file with the flagged items. This is especially helpful if you run Vale against a directory with multiple files.
+Here are some resources to help you create good titles and descriptions for SEO:
 
-4. Each flag tells you the line and location of the flagged item, the level of the flag (error, warning, or suggestion), and a suggestion for how to resolve the flag.
+- [Google's recommendation on good titles](https://developers.google.com/search/docs/advanced/appearance/title-link?hl=en)
+- [Google's recommendation on good descriptions](https://developers.google.com/search/docs/advanced/appearance/snippet?hl=en)
 
-5. Once you have addressed the flagged items and made edits as needed, you can complete the normal steps to commit your changes and open a pull request to review for merge.
+In general, titles should be between 50 and 60 characters and descriptions should be between 120 and 160 characters.