mushroom-strategy/docs/contributing/documentation.md

📄 Contributing to the Documentation

Good documentation is crucial for our project's success!
We truly appreciate any contributions, whether it's fixing a typo, clarifying a section, adding more examples, or even extending existing topics. This guide will walk you through the process of contributing.

The entire documentation lives in the docs/ folder of this repository.

---

1. Follow the Workflow:

2. Serve the Documentation Locally: Start the local development server. This task needs to be run from the project root (where the mkdocs.yml file is):

   mkdocs serve
   

   This will usually launch a local server, at http://127.0.0.1:8000. The server will automatically reload in your browser as you make and save changes to the documentation files.
   To stop the server, press Ctrl + C in the terminal.

3. Edit Markdown Files: All documentation content is written in Markdown (.md files). You can find them within the docs/ folder.

   • For advanced formatting options, refer to the Material for MkDocs reference.

4. Add New Pages:

   • Create a new .md file in the most appropriate directory within docs/.

   !!! important

    You'll need to add the new page to the navigation (`nav`) section of the `mkdocs.yml` file for it to appear in
    the sidebar. Follow the existing structure.
   

5. Add Images:

   • Place any image files into the docs/images/ directory.
   • Reference them in your Markdown using the syntax: ![Alt text for accessibility](images/your-image-name.png)

6. Preview Changes: As you save your .md files, the local server running at http://127.0.0.1:8000 will automatically refresh, allowing you to see your changes instantly.

7. Format and Lint Your Changes:

   • Build the linter with npm run md:lint-fix.

   This task should result without errors.

8. Commit Your Changes.

9. Push to Your Fork.

10. Open a Pull Request (PR).

---

Documentation Style and Quality

To maintain consistency and quality:

• Clarity and Conciseness: Use straightforward, clear, and concise language.
• Examples: Include images and code examples whenever they help clarify a point.

---

Thank you for taking the time to help us improve our documentation! Your contributions make a real difference. 🎉