documentation-standards git:20260825.8b78171A

Immutable. This exact content is served forever at /api/v1/blob/cb13674a5d872fd0.

---
name: documentation-standards
description: >-
  Documentation best practices including Markdown formatting, Mermaid diagrams,
  technical writing, ADRs, Docusaurus and MDX documentation sites, and open
  source standards. Use when writing documentation, README files, Markdown or
  MDX content, creating static diagrams in Markdown, configuring Docusaurus, or
  asking about documentation structure, technical writing, or open source
  project setup. For interactive React Flow canvases in a SPA, use the
  reactflow-architecture-diagrams skill instead.
---

# Documentation Standards

Mandatory Markdown gates are owned by the Markdown rule (`${HANDBOOK_ROOT}/rules/800-markdown.mdc`). This skill owns document design, Mermaid guidance, templates, and writing workflows.

## Core Principles

1. **Audience-First**: Write for your reader, not yourself
2. **Keep Current**: Outdated docs are worse than no docs
3. **Show, Don't Just Tell**: Use examples and diagrams
4. **Consistent Format**: Follow established patterns

## Hard Requirements (Writing)

- **No AI slop** - remove filler, keep docs concrete and task-oriented
- **No Unicode em dashes or en dashes** - never author `U+2014` or `U+2013`; use commas, colons, parentheses, semicolons, or ASCII hyphens instead
- **Clickable navigation** - if readers may want to open a repo file, directory, section, ADR, rule, skill, script, workflow, or config, make it a Markdown link. Use backticks only when the path is a literal value, not a navigation target.
- **Official terminology** - use each vendor's current official product and service names, capitalization, and branding. Verify uncertain names against current vendor documentation. For example, write **Amazon VPC**, not **AWS VPC**; write **AWS Lambda**, not **Amazon Lambda**. Do not apply one naming prefix mechanically across a provider's services.

## Voice

Prefer neutral/imperative phrasing - avoid "you/your" in professional docs.
Canonical guidance: `rules/810-documentation.mdc`.

## Diataxis Quick Guide

Use one primary documentation mode per page:

- **Tutorial** - learning by doing
- **How-to guide** - task completion
- **Reference** - factual lookup
- **Explanation** - concepts and rationale

Canonical Diataxis guidance lives in `rules/810-documentation.mdc`. Keep this skill concise and link back to the rule instead of duplicating detailed standards.

## Documentation Sites and Docusaurus

Use a documentation site when the content needs structured multi-page
navigation, search, versioning, internationalization, or interactive MDX.
Keep a README and a small set of Markdown guides when those capabilities do not
justify a separate Node.js build and deployment lifecycle.

For Docusaurus work:

- Verify the current supported Docusaurus, Node.js, React, and plugin versions
  from official sources. Pin compatible releases and commit the lockfile.
- Treat MDX as executable React code. Never compile untrusted content as MDX.
- Configure search explicitly. Docusaurus does not make a site searchable
  without a search integration and index lifecycle.
- Version only supported release lines, not every patch by default.
- Make the production build fail on broken internal links and verify `url`,
  `baseUrl`, and `trailingSlash` against the deployment path.

Use the Docusaurus reference
(`${HANDBOOK_ROOT}/skills/documentation-standards/references/docusaurus.md`) for
site structure, MDX trust boundaries, versioning, search, CI, and deployment.

## README Structure

```markdown
# Project Name

Brief description of what this project does.

## Features

- Feature 1
- Feature 2

## Installation

```bash
npm install my-project
```

## Quick Start

```javascript
import { thing } from 'my-project';
thing.doSomething();
```

## Documentation

Link to full docs.

## Contributing

Link to CONTRIBUTING.md.

## License

MIT - See LICENSE.

```

## Markdown Best Practices

### Headers
- Use `#` hierarchy (don't skip levels)
- Keep headers concise
- Use title case for headings, preserving established acronyms and product names

### Code Blocks
````markdown
```python
def hello():
    print("Hello, World!")
```

````

### Lists
```markdown
- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Another item
```

### Links and References
```markdown
[Link text](https://acme.com)
[Reference link][1]
Python rule (`${HANDBOOK_ROOT}/rules/200-python.mdc`)
Bash rule (`${HANDBOOK_ROOT}/rules/140-bash.mdc`)

[1]: https://acme.com
```

Prefer clickable same-repo references:

- Good: `Python skill (`${HANDBOOK_ROOT}/skills/python-development/SKILL.md`)`
- Avoid for navigation: `` `skills/python-development/` ``
- Good for literals: `` `src/app.ts` `` when discussing a path value or config example

### Tables
```markdown
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
```

## Interactive vs static diagrams

- **Static (Markdown):** Mermaid in this skill and in `rules/800-markdown.mdc`.
- **Interactive (React SPA):** `@xyflow/react` patterns, playbook, and rule **`rules/815-reactflow-diagrams.mdc`** - use skill **`skills/reactflow-architecture-diagrams/`**. See static versus interactive diagrams (`${HANDBOOK_ROOT}/skills/reactflow-architecture-diagrams/references/static-vs-interactive.md`) for a short comparison table.

### AI diagram tooling

Prefer tools that preserve a code-owned source of truth. Mermaid text in the repo is easiest to review, diff, and maintain.

| Tool | Best fit | Round-trip / ownership guidance |
|---|---|---|
| **Mermaid Chart AI** | Best fit for engineering-maintained diagrams | Generates/refines standard Mermaid and can export PNG, SVG, or MMD. Keep the `.mmd` / Mermaid block in the repo as source of truth. |
| **Eraser** | Good for nicer engineering visuals | Can import Mermaid and export PNG/SVG/PDF. Mermaid round-tripping is weaker, so treat exported Mermaid as a starting point and review manually. |
| **Lucidchart AI** | Good for polished business-friendly diagrams | Supports Mermaid input, but generated diagrams are not ideal for code-based round-tripping. Use for stakeholder diagrams, not canonical repo-maintained architecture diagrams. |
| **Napkin AI** | Best for presentation / infographic visuals | Exports PNG/SVG/PPT/PDF, but not Mermaid. Use for slides or narrative visuals, not engineering diagrams that must remain code-owned. |

Rule of thumb: if future maintainers need to edit it in Git, use Mermaid (or React Flow for interactive SPA diagrams). If the artifact is for a deck or executive narrative, exported visuals are acceptable as generated artifacts.

## Mermaid Diagrams

### Flowchart
```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

### Sequence Diagram
```mermaid
sequenceDiagram
    participant User
    participant API
    participant DB
    
    User->>API: Request
    API->>DB: Query
    DB-->>API: Result
    API-->>User: Response
```

### Architecture Diagram
```mermaid
graph LR
    subgraph Frontend
        A[React App]
    end
    subgraph Backend
        B[API Gateway]
        C[Service]
    end
    subgraph Data
        D[(Database)]
    end
    
    A --> B
    B --> C
    C --> D
```

## Technical Writing Tips

1. **Use active voice**: "The function returns a value" not "A value is returned"
2. **Be concise**: Remove unnecessary words
3. **Define acronyms**: Spell out on first use
4. **Use present tense**: "The function adds" not "The function will add"
5. **Include examples**: Show, don't just tell

## Detailed References

- **React Flow (interactive canvases)**: See `skills/reactflow-architecture-diagrams/SKILL.md` and `rules/815-reactflow-diagrams.mdc`
- **Docusaurus**: See Docusaurus documentation sites (`${HANDBOOK_ROOT}/skills/documentation-standards/references/docusaurus.md`)
- **Markdown & Mermaid**: See Markdown and Mermaid (`${HANDBOOK_ROOT}/skills/documentation-standards/references/markdown-mermaid.md`)
- **Technical Writing**: See technical writing (`${HANDBOOK_ROOT}/skills/documentation-standards/references/technical-writing.md`)
- **Open Source**: See open source (`${HANDBOOK_ROOT}/skills/documentation-standards/references/open-source.md`)