Design Doc

Authors and reviews software design documents — the written artifact an engineer produces before building, to think through the decisions that are expensive to get wrong. This skill is the judgment for three questions the article centers on: should this project have a doc at all, what goes in it, and how do you write it so it actually works on a reader who never spoke to you.

A design doc is not a formality or a status report. Its purpose is leverage:

A good design doc can save you years of development time. Writing a design doc forces you to think through important decisions before you waste time on the wrong implementation or paint yourself into a corner.

It is two things at once: a decision-forcing tool (writing the hard parts down surfaces the choices you'd otherwise discover mid-build, when they're costly to reverse) and a communication tool (it lets teammates, partner teams, and reviewers understand and pressure-test the plan before code exists).

The Two Ways a Design Doc Fails

Hold both failure modes in mind the entire time. Every decision in this skill is about staying between them.

• Under-writing — skipping the doc, or omitting the decisions that are hard to reverse. You discover the mistake after 200k lines of C++, when a rewrite is unrecoverable. The cure is the when-to-write test and the penalty-for-being-wrong filter.
• Over-writing — specifying every detail (button spacing, every helper). "If you specify every possible detail in a design doc, you've essentially written the implementation during the design phase. That would defeat the whole purpose of a design doc." The cure is the same penalty-for-being-wrong filter, applied to cut.

Good design-doc work is almost entirely about what to leave out. Reach for high-cost-of-error decisions; let cheap, reversible choices be discovered in code.