git:20260819.d23bb73 to git:20260825.8b78171

---

name: documentation-standards

description: >-

Documentation best practices including Markdown formatting, Mermaid diagrams,

---

# 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.

## 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`

- **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`)