---
name: writing-system-documentation
description: Creates task-oriented technical documentation with progressive disclosure. Use when writing READMEs, API docs, architecture docs, or markdown documentation.
---

# Technical Documentation

## Core Principles

### 1. Progressive Disclosure

Reveal information in layers:

| Layer | Content | User Question |
|-------|---------|---------------|
| 1 | One-sentence description | What is it? |
| 2 | Quick start code block | How do I use it? |
| 3 | Full API reference | What are my options? |
| 4 | Architecture deep dive | How does it work? |

**Warnings, breaking changes, and prerequisites go at the TOP.**

### 2. Task-Oriented Writing

```markdown
<!-- ❌ Feature-oriented -->
## AuthService Class
The AuthService class provides authentication methods...

<!-- ✅ Task-oriented -->
## Authenticating Users
To authenticate a user, call login() with credentials:
```

### 3. Show, Don't Tell

Every concept needs a concrete example.

## Writing Standards

- **Sentence case headings**: "Getting started" not "Getting Started"
- **Max 3 heading levels**: Deeper means split the doc
- **Always specify language** in code blocks
- **Relative paths** for internal links
- **Tables** for structured data with 3+ attributes

## Quality Checklist

- [ ] Code examples tested and runnable
- [ ] No placeholder text or TODOs
- [ ] Matches actual code behavior
- [ ] Scannable without reading everything
- [ ] Reader knows what to do next

## Anti-Patterns

| Problem | Fix |
|---------|-----|
| Wall of text | Break up with headings, bullets, code, tables |
| Buried critical info | Warnings/breaking changes at TOP |
| Missing error docs | Always document what can go wrong |
| Cross-artifact enumeration | Reference by structure (capability → test class), not by line-item. Per-scenario tables mirror requirements and go stale on any change. Describe *how* capabilities are tested, not *which* scenarios exist — that's owned by the requirements files. |

## Diagrams

Use Mermaid for architecture and flow diagrams. Key principles:
- **Visual hierarchy over decoration** — use fills for grouping, stroke for critical paths
- **Semantic shapes** — consistent shape-to-role mapping at your level of abstraction:

  | Role | System level | Component level | Data flow level |
  |------|-------------|-----------------|-----------------|
  | Processing | rectangles (services, apps) | rounded rectangles (modules, classes) | rectangles (transforms, steps) |
  | Boundaries | subgraphs (system boundaries) | rounded rectangles (interfaces, ports) | diamonds (decisions, branches) |
  | Storage | cylinders (databases, stores) | cylinders (caches, queues) | parallelograms (inputs, outputs) |

- **7-12 nodes max** — if you can't grasp it in 10 seconds, split it
- **Layout** — LR for pipelines/data flow, TB for hierarchies/decision trees
- **Styling** — max 5 colors, avoid pure black, ensure contrast on dark backgrounds