Writing Docs

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

ngrx Updated

File contents

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.

ngrx/platform/tree/main/.agents/skills/writing-docs commit 67e338f9cc

Frequently asked questions

npx skillmds@latest add ngrx/writing-docs