Writing Documentation
Apply when writing, editing, or reviewing docs.
Voice and style
- Impersonal: No "you", "your", or second-person imperatives.
- Statements over imperatives: Prefer "Tests should not spy" over "Avoid spying"; passive or descriptive phrasing.
- Titles: Gerunds, not imperatives (e.g. "Testing the store" not "Test the store").
- Tone: Direct and minimal; every sentence adds information.
Formatting
- Dashes: Space-hyphen-space (
-), not em dash (—). - Paragraphs: Merge single-sentence paragraphs when it helps readability.
Code examples
- Examples: Simple, self-contained (e.g. Counter, Books). Short snippets; shorten or link out long async flows unless the topic is async.
Structure and navigation
- Section titles: Accurate and scannable.
- Links over repetition: Link to other guides; explain only what is specific to this page.