Overview
Technical writing standards for developer documentation exist to get a reader to a working result fast, with the least prose. Good docs are task-first, scoped to one job per page, built on examples a reader can run, and written in precise, consistent terms. They are versioned and tested like the code they describe. This is the writing-cluster pillar for documentation; for the voice rules see voice, and for docs aimed at AI products and agents see documentation-for-ai-products.
Write task-first, lead with the goal
Organize around what the reader is trying to do, not around the system’s internal structure. Title pages with the task (“Deploy a static site”), and open each with the outcome and prerequisites. State the result up front so a reader knows in one sentence whether the page is the right one; this is the answer-first pattern applied to docs. See answer-first-content.
Scope one job per page
A page should answer one question completely. When it grows past a single task, split it and link the parts. Atomic pages are easier to find, keep current, and cite. Long catch-all pages rot because no one owns the whole thing. This mirrors the vault’s own atomic structure; see articles.
Show runnable, tested examples
Code beats description. Give complete, copy-and-paste examples that run as written, including imports and setup, and show expected output. Test the examples in CI so they cannot drift from the API. A broken example costs more trust than a missing one.
Use precise, consistent terminology
Name each concept once and use that name everywhere; do not alternate synonyms for variety. Define a term on first use and link to a glossary entry for the rest. Ambiguous or shifting terms are the most common source of doc confusion. Follow editorial-style for capitalization, numbers, and code references.
Keep the voice plain and the structure scannable
Lead with the rule, then the rationale. Short declarative sentences, active voice, and descriptive headings let a reader skim to the part they need. Cut the slop preambles and filler that pad without informing; see anti-slop and voice.
Version and maintain docs with the code
Docs are part of the product. Keep them in the repo, review them in the same pull request as the code change, and date or version them so a reader knows what release they describe. Stale docs are worse than none because they mislead. A CLAUDE.md or contributor guide is documentation too; see write-claude-md-from-scratch and claude-code-claude-md.
Pitfalls
- Reference-only docs with no task or tutorial path for newcomers.
- Examples that omit setup and cannot actually run.
- Synonym-swapping that makes one concept look like three.
- Docs in a separate repo that drift from the code they describe.