Skip to content

Documentation Standards

To ensure clarity, consistency, and usefulness across all documentation, follow these standards:

1. Structure

  • Begin each document with a clear title and a brief summary.
  • Use hierarchical headings (#, ##, ###) for organization.
  • Include navigation links to related docs where relevant.
  • Add an “Update History” section at the end if the document is frequently revised.

2. Content

  • Write in clear, concise, and professional language.
  • Use bullet points, tables, and diagrams for complex information.
  • Provide step-by-step instructions for setup, onboarding, or processes.
  • Reference external resources and internal links as needed.

3. Templates

  • Use provided templates for proposals, changelogs, design docs, and wild ideas.
  • Place new documentation in the appropriate directory and update the relevant README/index.

4. Review Process

  • Submit documentation changes via pull request.
  • Tag at least one reviewer familiar with the topic.
  • Ensure all links and references are up to date.

5. Style

  • Prefer American English spelling.
  • Use present tense and active voice.
  • Avoid jargon unless defined in a glossary.

6. MkDocs Guidelines

  • All documentation is now rendered using MkDocs with the Material theme.
  • When adding new pages, update the nav section in docs/mkdocs.yml to include them.
  • Use MkDocs-specific features like admonitions, tabs, and code blocks with syntax highlighting: 
    !!! note "Note Title"
    This is a note admonition.

=== "Tab 1"
    Content for tab 1

=== "Tab 2"
    Content for tab 2

```python
# This is a Python code block with syntax highlighting
def hello_world():
    print("Hello, world!")
    ```
  • Preview changes locally by running .mkdocs/serve.sh before submitting.
  • Use relative links to other documentation pages (e.g., [Link Text](../path/to/file.md)).

7. Cloudflare Pages Deployment

  • Documentation is automatically deployed to Cloudflare Pages when changes are pushed to the main branch.
  • The deployment is configured in the cloudflare-pages.toml file in the repository root.
  • The documentation is available at https://meta-agent-platform.pages.dev/.
  • To build the documentation locally, run: 
    ./.mkdocs/build.sh
  • Always check the deployed documentation after pushing changes to ensure everything looks correct.

Last updated: 2025-04-16