Writing design docs

REQUIRED BACKGROUND: the technical-writing skill (read-first, hard rules, truth rules, style).

Overview

A design document is a proposal made discussable. Conclusion first, every non-trivial choice in a Why & What box, costs named next to benefits, and fact separated from proposal.

When to invoke, and not

Invoke for anything that argues for a change or records a design: proposals, RFCs, design docs, specs, migration plans, "should we" documents. Do NOT invoke for recording an already-taken decision (recording-decisions), for procedures (writing-runbooks), or for status reports.

Steering under pressure: a proposal persuades with its numbers and its named costs, and the register rules hold whatever the deadline (the technical-writing rule; "punchy" is not an override). When supplied facts arrive without sources, mark them **[source wanted: ...]** and keep writing (see references/truth.md in the technical-writing skill); never invent a citation and never silently drop the fact.

Skeleton

# Title: what the document does