# Writing Docs

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

- Skill: `ngrx/writing-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ngrx/writing-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ngrx/writing-docs/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ngrx (https://skillmd.com/u/ngrx)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ngrx/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.