technical_writing v1.0.0

name: "technical_writing" description: "Write technical documentation people actually finish: guides, references, READMEs, and runbooks. Triggers when the user asks for documentation, a README, a how-to guide, an API reference, a runbook, or when reviewing/editing technical prose."

Technical Writing

Purpose

Turn technical knowledge into documentation that people finish and can act on. Readers scan, they don't read: a Nielsen Norman Group study found 79% of web users scan new pages instead of reading word-by-word. Write for the scanner first, the careful reader second.

Workflow

1. Classify the document (Diátaxis). Ask two questions:

• Does the reader need action or cognition?
• Are they acquiring skill or applying it?
• action+acquiring → tutorial (guided learning, handhold, assume nothing)
• action+applying → how-to guide (task steps, assume baseline knowledge)
• cognition+applying → reference (complete, accurate, no narrative)
• cognition+acquiring → explanation (why, context, trade-offs, no steps) Never write two types in one document; it produces a worse version of both.

1. Define the reader and the job. One sentence: who reads this, and what can they do after? State prerequisites and what's not covered if they'd expect it.
2. Structure task-first. How-tos and tutorials: lead with the goal, put conditions before instructions ("If X, do Y"), one action per numbered step, start each step with an action verb. References: structured for lookup, not narrative. All types: key information in the opening summary (inverted pyramid).
3. Draft in example-first order. Show a working example before the theory that explains it. A reader with a working example will skim the theory; a reader with theory and no example will leave.
4. Edit for scanners. See references/editing-checklist.md. The scan test: headings + bold + list leads alone must tell the story.
5. Apply style rules. See references/style-rules.md (Google and Microsoft conventions: second person, active voice, present tense, imperative procedures, sentence-case headings, serial commas).
6. Verify every fact. Trace claims back to code, docs, or a primary source. Never invent numbers, dates, quotes, or behaviors. Unverifiable = cut it.

Output Contract

A finished document has: a classified type (tutorial / how-to / reference / explanation) stated or evident; a reader+job definition; task-oriented structure matching its type; examples before theory; every factual claim traceable to a source; style per references/style-rules.md; and it passes the scan test.

Operating Rules

1. Facts come from primary sources (official docs, the code, standards bodies). No confident unverified claims, ever.
2. One idea per paragraph; one main idea per sentence; short paragraphs.
3. Address the reader as "you"; instructions in the imperative ("Run the migration", not "You should run the migration").
4. Never write marketing copy into technical docs — no unsupported superlatives, no boastful claims.
5. Never anthropomorphize software: it returns, reports, fails — it never knows, wants, or tries.
6. Keep docs timeless: no "currently", "new", "now" unless time is essential.
7. Bulky examples, rewrite pairs, and the full checklist live in references/; SKILL.md stays the operational core.