Writing style for docs
Readers are agents and busy humans. Every word costs context.
Density
- Lead with the point. No intros, no "this document describes", no summaries of what follows.
- Fragments are fine. Cut every word that carries no information.
- One fact, one place. Link instead of restating.
- Don't paraphrase code. Point at it with code: and add only what the code can't say:
why, invariants, gotchas.
Shape over prose
| content | use |
|---|---|
| flow, sequence, dependencies | mermaid flowchart / sequenceDiagram |
| lifecycle, statuses | mermaid stateDiagram-v2 |
| data shapes, contracts | schema block (typed fields, units, nullability) |
| comparisons, options, mappings | table |
| steps | numbered list, one action each |
| reasoning, trade-offs | short prose, the only place for it |
Precision - Concrete names: real modules, tables, fields, commands. No "the service", "various components". - Units and ranges on every number. Say what's guaranteed and what's merely usual. - A short example beats a long explanation.
Hygiene - No dates or "recently" in current-state docs. Git has the history; ADRs have the why. - No TODOs in docs. Log a papercut instead. - If a section needs a heading to be findable, it probably wants its own file.