Technical Writing

Technical Writing: Skimmed First, Trusted Enough to Finish

Developers skim before they commit. A document earns the full read by answering three questions in its first screen: what is this, why should I care, and how do I start. Everything below serves that contract.

One Primary Reader Job Per Page

Choose the page's primary reader job: tutorial, how-to, reference, or explanation (Diátaxis; its honest limits live in resources/doc-types.md). Supporting material may cross a boundary when that helps the same job. Split the page when mixed purposes make the next action, completeness contract, or intended audience unclear.

Principles

• Reader-first — lead with the payoff; the reader's next action is the organizing principle, not the system's internal structure. Name things by what readers recognize, not how the code is built.
• Scannable — clear headings that summarize their section's payoff, short paragraphs, purposeful emphasis. Add a heading when it gives a skimmer a useful landmark; do not optimize for a word-count quota.
• Plain and direct — active voice, second person for instructions, short sentences for complex ideas. Complete sentences beat fragments and arrow chains: readable matters more than terse.
• Selective, not compressed — the way to keep a doc short is to cut what doesn't change the reader's next step, never to compress the prose into jargon the reader must decode.

Material Claims Need Receipts

Make material capability, current-state, compatibility, and quantitative claims checkable. Explanatory prose, clearly labelled judgment, and normative design rationale do not need a fake command or date; unsupported promotional claims do.

• No capability claim without evidence: numbers a reader can verify, a command they can run, a file they can open. "Fast" is marketing; "the gates run in 14 seconds on this repo's CI" is a claim with a receipt.
• Counts and versions rot: changing operational numbers quoted in prose (test counts, coverage, versions) are maintenance liabilities — either generate it, date it, or bind it to the kept-current rule (updating it is part of every change's definition of done).
• Honest limits are content, not confession: when the page's scope could imply protection, coverage, or capability it does not provide, name those limits where the reader makes the decision. A short document need not grow a ceremonial limits section when its bounded scope is already explicit.
• Idle and empty states must speak: "0 items processed" that reads like success is a lie of layout. Distinguish "nothing to do" from "did nothing" everywhere output appears in docs and examples.
• Timeless maintained guidance: evergreen READMEs and reference docs avoid unowned "coming soon", "currently", or "new in…" labels. Release notes, migration guides, deprecation notices, and time-bounded status pages may need temporal language; attach a version/date and an owner or removal condition so it remains evidence instead of stale promotion.

Docs Are Behavior — Verify Them

A document that describes a system is a claim about that system, and claims get verified:

• Verify against the source, not memory: every material flag, exit code, config key, and executable command a doc asks readers to rely on is checked against the code before it ships. Execute the claim when doing so is safe, authorized, and proportionate; otherwise record the evidence gap.
• Machine-check what machines can check: table-of-contents anchors against the renderer's real slug rules, links against files, command examples against the binary. Hand-verification is the fallback, not the default.
• Update docs in the same reviewable change: a behavior change that leaves its documentation stale is incomplete work. Follow the repository's commit policy rather than imposing one globally.