technical-writinglisted

# Technical Writing Docs are the contract (Rule 0/19) — code follows prose, not the reverse. A doc that buries its point, mixes altitudes, or restates the code is worse than no doc: it costs every future reader the time to discover it's useless. This skill makes "a reader acts on it the first time" the bar. > Scaffold a doc with the house header already correct: > `python3 scripts/new_doc.py --layer playbook --domain BACKEND --title "Service X runbook" --root docs/playbooks` > **The doc *system* — taxonomy, layers, naming, header rules — is governed by > [docs/governance/docs-system.md](../../../docs/governance/docs-system.md) (SSOT).** > This skill is the *craft* layer on top: how to write each layer *well*. ## The five craft rules 1. **Altitude — match detail to the reader's decision.** An index routes; a playbook sequences; a reference exhausts; an ADR justifies. Don't put reference-grade tables in a playbook, or hand-wave in a spec. Ask "what does the reader decide here?" and write exactly that. 2. **One idea per section.** A heading is a promise. If a section covers two things, split it. The reader scans headings first — they must predict content. 3. **Active voice, present tense, specific subject.** "The hook blocks the write" not "the write may be blocked". Name the actor. 4. **Specificity over vagueness.** "completes in <50 ms on the highest-degree hub" beats "is fast". Numbers, file paths, exact commands — never "appropriately" or "as needed". 5. **Bad→good for