---
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.
2. **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.
3. **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).
4. **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.
5. **Edit for scanners.** See `references/editing-checklist.md`. The scan test:
   headings + bold + list leads alone must tell the story.
6. **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).
7. **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.