Written Design Document

The reason writing works is that prose does not permit vagueness the way a diagram does. A box labelled "sync service" with two arrows conceals every hard question; a paragraph describing what it does when the downstream is unavailable, how it handles duplicates, and what happens to state on restart cannot conceal them. Authors routinely discover the design is unfinished while writing it, which is the point.

The shape that works: the problem and why it matters, the constraints, the proposed approach in enough detail to be criticised, the alternatives considered and rejected with reasons, the risks and open questions stated honestly, and the impact on cost, operations, security and other teams.

The section that distinguishes a good document is open questions. A proposal presenting complete confidence invites either rubber-stamping or a hunt for holes; one that names its own uncertainties directs reviewers to where their input is worth most.

The process matters as much as the artifact. Circulate for a defined comment period, respond to comments in the document so the reasoning is preserved, and record the outcome. The comment thread becomes the most valuable part of the record, because it captures the objections and their resolution — exactly what a future reader needs and what a clean final document omits.