writing-docs

name	writing-docs
description	Doc conventions (impersonal style, formatting, Vitest in examples, structure, linking). Use when writing, editing, or reviewing guides, tutorials, or READMEs.

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.