Writing design docs
REQUIRED BACKGROUND: the
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 (
), for procedures (
), or for status reports.
Steering under pressure: "management wants it punchy", "sell it", and deadlines do not relax the tone rules. A proposal persuades with its numbers and its named costs; the moment it reads as a pitch, it loses the reader this skill writes for. When supplied facts arrive without sources, mark them
and keep writing (see
); never invent a citation and never silently drop the fact.
Skeleton
markdown
# Title: what the document does
**Subtitle pinning the scope in one sentence**
| -------------- | ------------------------------------------ |
| **Status** | Draft / Request for comments |
| **Owner** | [team or role] |
| **Scope** | [explicit, including what falls outside] |
| **Related** | [links to sibling documents] |
| **Audience** | [who must read this] |
---
## 1. Summary
[The answer immediately. Not the occasion, not the method: the conclusion.]
## 2. [Context / what was analyzed]
## 3. [The analysis, split per question]
## n. Open questions
## n+1. Benefits and costs
[Both. A proposal that lists only benefits reads as a sales pitch.]
---
*Closing line: which parts are fact and which are proposal, and where input is wanted.*
Structure rules
- Number chapters and cite them as . Numbers make feedback addressable: readers can point at one.
- Goals and non-goals both. The non-goals (or "explicitly not changed") section is where scope creep dies in writing; it is the highest-leverage section in any spec. State what stays unchanged.
- Definitions before behavior when a term is ambiguous: pin "responded", "eligible", "stale" before using them.
- A grounding section pins the facts the design rests on: a fact/source table, checked against a named commit. Separate verified facts from what will be built.
- Appendices take letters (Appendix A, B) and hold what would bury the main text: config examples, glossaries, inventories.
- A fact lives in one place. Link to it; never repeat it, not even across documents in the same repo.
- Mark unfinished parts with
**[DRAFT - input wanted]**
- Open questions get owners: a name, a role, or an explicit "to be filled by".
- Residual risks and what NOT to do close the document when the design ships work to others.
- No line budget, but length from repetition or emphasis goes; past roughly 800 lines, split and let the main document point.
The Why & What box
Every non-trivial choice gets one. It makes a proposal discussable instead of announced: readers react to the box, not to the conclusion.
markdown
> **Why & What - [the choice in four words]**
>
> **What:** [the choice, one sentence, no justification]
>
> **Why:** [the reasoning. Also name what the choice does NOT solve.]
>
> **Alternatives considered:**
> - *[Alternative]:* [its strongest argument, and why it still lost]
>
> **Fallback:** [what survives if this does not work]
Rules for the box:
- An alternative dismissed without its strongest argument is a strawman. Name that argument.
- Admitting what the choice does not solve makes the document more credible, not weaker.
- No box for choices nobody would contest; that is noise.
- An alternative that appears nowhere else in the document does not belong in the box: such a rejection records what the writer once thought, while the reader would never consider the option. One can be right; several short ones in a row are a sign.
Tone
- It stays a proposal: "we propose" and "whether that convinces is up to you", not "this becomes the way of working". Broad lines give direction; the fill-in stays open.
- Name what it costs. The benefits chapter ends with the price: what gets harder, what people must unlearn, which freedom disappears.
- No superlatives, no promise language. Concrete figures and verifiable statements.
- The expected outcome may be negative, and saying so up front is honest writing: "the expected outcome is that buy-and-hold wins; that is a useful result."
Completeness check
Before handing a spec or plan to a reviewer or executor, check the five vagueness defects:
- Unresolved placeholders: any literal TBD, TODO, "fill in later", or clearly incomplete sentence (a marked block is deliberate; an unmarked gap is a defect).
- Missing acceptance criteria: a requirement with no concrete, independently testable success condition.
- Undefined references: a type, endpoint, component, or table mentioned but defined nowhere.
- No verifiable output: a task producing nothing a reviewer could inspect (no file path, no command, no observable behavior).
- What without how: an outcome with no implementable direction ("handle errors appropriately" with no definition of appropriate).
For execution plans, add per task: goal, exact files, the change shown, tests with concrete scenarios, and the verify command. Explain any confusing leftover (an odd directory name, a legacy alias) rather than leaving it puzzling.