writing-docs

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