Documentation Standards

This guide outlines the standards and best practices for contributing to MAID documentation. Following these guidelines ensures consistency, accessibility, and maintainability across all documentation.

Writing Style

Voice and Tone

• Use active voice: Write "MAID processes events" instead of "Events are processed by MAID"
• Be direct: Get to the point quickly. Users want answers, not prose
• Use second person: Address the reader as "you" for instructions
• Be inclusive: Use gender-neutral language and avoid jargon when possible

Clarity

• One idea per sentence: Break complex thoughts into multiple sentences
• Define acronyms: Spell out acronyms on first use, e.g., "Entity Component System (ECS)"
• Use concrete examples: Abstract concepts should be followed by practical examples
• Avoid ambiguity: "Click the button" is clearer than "Click it"

Technical Writing

• Present tense: Use present tense for descriptions ("The function returns..." not "The function will return...")
• Imperative mood for instructions: "Run the command" not "You should run the command"
• Consistent terminology: Use the same terms throughout (don't alternate between "content pack" and "plugin")

Document Structure

Page Organization

Every documentation page should follow this structure:

# Page Title

Brief introduction explaining what this page covers (1-2 sentences).

## Prerequisites (if applicable)

List what the reader needs to know or have installed.

## Main Content

Organize with clear headings (H2, H3).

## Next Steps (if applicable)

Link to related pages or natural follow-up topics.

Headings

• Use sentence case for headings: "Getting started" not "Getting Started"
• Start with H1 (#) for the page title
• Use H2 (##) for main sections
• Use H3 (###) for subsections
• Avoid skipping heading levels (don't go from H2 to H4)
• Keep headings concise and descriptive

Table of Contents

• MkDocs automatically generates the table of contents
• Ensure your headings form a logical hierarchy
• Limit to 3 levels deep in most cases

Code Examples

Code Block Standards

Always specify the language for syntax highlighting:

```python
def example_function():
    """This is a properly formatted code example."""
    return "Hello, MAID!"
```

Code Quality

All code examples must:

1. Be syntactically valid: Run uv run python scripts/validate_docs.py to check
2. Be complete when possible: Include imports and context
3. Follow MAID coding standards: Type hints, docstrings, async/await patterns
4. Be copy-paste ready: Users should be able to copy and run examples

Incomplete Code

When showing partial code, clearly indicate with comments:

# ... previous code ...

async def new_handler(event: Event) -> None:
    """Handle the event."""
    # Your implementation here
    pass

# ... rest of file ...

Code Annotations

Use code annotations for complex examples:

from maid_engine.core import World

async def setup_world():
    world = World()  # (1)!
    await world.initialize()  # (2)!
    return world

1. Create a new World instance
2. Initialize must be awaited before use

Long Code Blocks

For long code examples:

• Consider breaking into smaller, focused snippets
• Use collapsible sections for complete files
• Provide a link to the full source if available

??? example "Complete implementation"

    ```python
    # Full code here
    ```

Markdown Formatting

Text Formatting

Format	Usage	Example
Bold	Important terms, warnings	Important: Back up your data
Italic	Emphasis, introducing terms	The event bus handles messages
Code	Inline code, commands, file names	Run maid server start
Strikethrough	Deprecated content	Old API (deprecated)

Lists

Use bullet points for unordered lists:

• First item
• Second item
• Third item

Use numbered lists for sequential steps:

1. Install dependencies
2. Configure settings
3. Start the server

Admonitions

Use admonitions to highlight important information:

!!! note "Title"
    This is a note with additional information.

!!! warning "Title"
    This warns about potential issues.

!!! danger "Title"
    This indicates a critical warning.

!!! tip "Title"
    This provides a helpful tip.

!!! example "Title"
    This shows an example.

Available admonition types:

Type	Use For
note	Additional information
tip	Helpful suggestions
info	General information
warning	Potential issues
danger	Critical warnings
example	Code examples with context
quote	Quotations
abstract	Summaries

Tables

Use tables for structured data:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

Keep tables simple and readable. For complex data, consider using description lists or nested structures.

Links

Internal links (to other docs pages):

See the [configuration guide](../reference/configuration.md) for details.

External links:

See the [Python documentation](https://docs.python.org/) for more information.

Anchor links (to headings on the same page):

See [Code Examples](#code-examples) above.

Images and Diagrams

When to Use Images

• Screenshots for UI-related documentation
• Diagrams for architecture and data flow
• Avoid images for content that can be expressed in text

Image Guidelines

1. Format: Use PNG for screenshots, SVG for diagrams
2. Size: Keep under 200KB when possible
3. Alt text: Always provide descriptive alt text
4. Location: Store in docs/assets/images/

Image Syntax

![Alt text description](../assets/images/filename.png)

Mermaid Diagrams

Use Mermaid for diagrams when possible (version controlled, editable):

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
```

Architecture Diagrams

For system architecture, use consistent styling:

graph TB
    subgraph "Content Pack Layer"
        CP[Content Pack]
    end
    subgraph "Standard Library"
        SL[maid-stdlib]
    end
    subgraph "Engine Layer"
        E[maid-engine]
    end
    CP --> SL
    SL --> E

API Documentation

Docstring Format

Use Google-style docstrings:

def process_event(event: Event, context: Context) -> Result:
    """Process an incoming event.

    This function handles event processing with the given context,
    applying all registered handlers.

    Args:
        event: The event to process.
        context: The processing context containing state.

    Returns:
        The processing result with status and data.

    Raises:
        EventError: If the event cannot be processed.
        ValidationError: If the event data is invalid.

    Example:
        >>> result = process_event(my_event, ctx)
        >>> print(result.status)
        'completed'
    """

Type Hints

Always include type hints in code examples:

from typing import Protocol

class Handler(Protocol):
    async def handle(self, event: Event) -> None:
        """Handle an event."""
        ...

Version-Specific Content

Marking Version Requirements

Use admonitions for version-specific features:

!!! info "Added in v0.2.0"
    This feature requires MAID v0.2.0 or later.

Deprecation Notices

!!! warning "Deprecated in v0.3.0"
    This API is deprecated and will be removed in v1.0.0.
    Use `new_api()` instead.

Accessibility

General Guidelines

• Provide alt text for all images
• Use semantic headings (don't skip levels)
• Ensure sufficient color contrast in diagrams
• Don't rely solely on color to convey information

Code Accessibility

• Use descriptive variable names in examples
• Add comments explaining non-obvious code
• Provide text descriptions for complex diagrams

Search Optimization

Making Content Searchable

MAID documentation uses MkDocs Material's built-in search, which provides:

• Search suggestions: As you type, the search shows likely completions
• Search highlighting: Matching terms are highlighted in search results
• Keyboard shortcuts: Press / to open search, Escape to close

Page-Level Search Control

Use frontmatter to control how pages appear in search:

Boosting important pages (make them rank higher):

---
search:
  boost: 2  # Values >1 rank higher, <1 rank lower
---

Excluding pages from search (e.g., drafts, templates):

---
search:
  exclude: true
---

Section-Level Exclusion

Exclude specific sections from search by adding a data attribute:

## Section to exclude from search { data-search-exclude }

This content will not be indexed by search.

Search-Friendly Writing Tips

1. Use descriptive headings: Headings are heavily weighted in search
2. Include synonyms: If users might search for different terms, include them
3. Front-load important content: Put key information early in the page
4. Use consistent terminology: Search works better when terms are consistent

Testing Search

Before submitting documentation:

1. Build the docs locally: uv run mkdocs build
2. Serve locally: uv run mkdocs serve
3. Test searching for your content
4. Verify results are relevant and well-ranked

Page Metadata

Frontmatter

Add frontmatter for page metadata:

---
title: Page Title
description: Brief description for search and social sharing
tags:
  - getting-started
  - tutorial
---

Tags

Use consistent tags across documentation:

Tag	Use For
getting-started	Introductory content
tutorial	Step-by-step guides
reference	API and configuration reference
advanced	Complex topics
troubleshooting	Problem-solving guides
content-pack	Content pack development
ecs	Entity Component System
events	Event system
commands	Command system

Quality Checklist

Before submitting documentation changes, verify:

• [ ] Spelling and grammar are correct
• [ ] Code examples are syntactically valid
• [ ] All links work (internal and external)
• [ ] Images have alt text
• [ ] Headings follow proper hierarchy
• [ ] Content is accurate and up-to-date
• [ ] Page renders correctly locally (mkdocs serve)
• [ ] Documentation validates: uv run python scripts/validate_docs.py

Building and Testing

Local Preview

# Start the documentation server
mkdocs serve

# Build static site
mkdocs build

# Validate code examples
uv run python scripts/validate_docs.py

Pre-commit Checks

Documentation changes are checked by CI for:

• Markdown linting
• Link validation
• Code syntax validation
• Build success

Getting Help

• Questions: Open a discussion
• Issues: Report documentation bugs via issues
• Improvements: Submit a pull request with your changes

Resources

• MkDocs Documentation
• Material for MkDocs
• Google Developer Documentation Style Guide
• Write the Docs