Why architecture matters here
The architecture matters because the alternative is not 'no design doc' — it is design decisions made implicitly, by whoever writes the first pull request, with no reviewers and no record. Those decisions still get made. They are simply made by one person at one moment with one context, and they become load-bearing before anyone else knows they exist. The doc does not add a decision to the process; it makes an existing decision visible while it is still cheap to change.
It matters because the expensive mistakes are almost never technical errors, and this shapes what the document must contain. Engineers rarely get the algorithm wrong. They get the problem wrong: they solve the case that was not the bottleneck, build for a scale that never arrives, or optimize a dimension nobody cared about. Those errors are invisible in code review, where the reviewer sees correct code and has no view onto whether it should exist. Only a document that states the problem before the solution can catch them, which is why the context section is not throat-clearing — it is the section that does the work.
The writing itself is a mechanism, not just a transmission. Committing a design to prose forces the vagueness out: you cannot write 'we will handle failures gracefully' in a sentence a reviewer will read and not immediately notice that you have said nothing. A significant fraction of design docs are abandoned partway through writing because the author discovers the design does not work. That is not a failed doc; that is the highest possible return on the practice, and organizations that measure docs by completion rate accidentally punish exactly this outcome.
The review structure matters as much as the content, because the goal is to surface disagreement and the default social dynamics suppress it. A meeting where a senior engineer speaks first anchors the room and the objections never arrive. A document circulated async, with comments landing before anyone gathers, lets people form independent views. This is the same logic as a blind code review or a written-first decision process: independence before aggregation, because a room that has already converged cannot un-converge, and the quiet objection is disproportionately often the correct one.
Finally, it matters because the durable artifact answers a question that recurs for years: not 'how does this work' but 'why is it like this'. The engineer who arrives in eighteen months and finds a strange constraint has two options — assume it was a mistake and remove it, or find the reasoning. Removing a constraint whose justification has been lost is a reliable source of outages. The decision log is the mechanism that makes the second option possible, which is why the rejected alternatives outlive the proposal in usefulness.
The architecture: every piece explained
Context and problem statement come first and carry the most weight. This section answers what is broken, who is hurt, how much, and why now — and 'why now' is the question that most often has no good answer, which is itself the finding. A context section that reviewers can read and independently conclude 'yes, this is worth solving' has done its job. One that assumes the problem and jumps to mechanism has smuggled the most important decision past review, and no amount of technical rigor downstream recovers it.
Goals and non-goals form the scope contract, and non-goals are the more valuable half. A goal list is aspirational and everyone nods. A non-goal list is a commitment: we are explicitly not solving multi-region, not supporting the legacy client, not optimizing for the batch case. Non-goals are what make review possible at all, because a reviewer can only evaluate a design against a bounded problem. They are also what protect the project later — scope creep is precisely the return of a non-goal, and a written non-goal turns that into a visible change request rather than a quiet slide.
The proposal is the section everyone thinks is the document, and it is genuinely the least interesting. It describes the design: components, data flow, interfaces, storage, the diagram. It should be concrete enough that a competent engineer could build from it and specific enough that a reviewer can disagree with something. Vagueness here is not modesty — it is an escape from review, and 'we will figure out the details in implementation' is the sentence that defers a decision past the point where it was cheap.
Alternatives considered is where the document earns its existence, and it is the section most often faked. A real alternatives section names two or three designs that a reasonable engineer would seriously propose and explains what specifically ruled each out — a benchmark, a constraint, a cost. Straw men are worse than nothing: they signal that the author either did not consider alternatives or is not being straight, and they destroy the reviewer's ability to trust the rest. This section is also the one that pays out years later, when someone asks why the obvious approach was not taken and the answer is written down.
Risks, rollback, and the decision record close it. Risks name what could go wrong and what the team would do about it — a risk without a response is an anxiety, not a risk. Rollback answers what happens when this ships and is wrong, and a design with no rollback story is a design with a much higher blast radius than its author believes. The decision record is the durable output: what was decided, by whom, on what date, with what reasoning and what alternatives rejected. That record is the only part guaranteed to still matter in two years, which is a strong argument for keeping it in a searchable log rather than in a document that will drift.
End-to-end flow
Start at the trigger. Someone notices a problem — latency drifting past an SLO, a component that cannot absorb next quarter's load, a recurring class of incident. The first move is not to open the template. It is a paragraph, shared with two or three people, saying 'I think this is a problem and I think it needs a real design; do you agree?' This costs twenty minutes and kills a meaningful fraction of docs before they are written, either because the problem is not real or because someone already solved it.
If it survives, the author writes a draft, and the ordering of the writing matters. Context first, then goals and non-goals, then alternatives — deliberately before the proposal. Writing alternatives first is uncomfortable, which is exactly why it works: it forces engagement with designs other than the one the author already likes. An author who writes the proposal first will produce an alternatives section that rationalizes it, every time, and will never notice they have done so.
The draft goes to a small group first — two or three people close to the problem — before wide circulation. This catches the embarrassing errors and the 'you know we already have a service that does this' comment in private, and it means the wide review spends its attention on the design rather than on obvious gaps. Wide review is expensive in aggregate attention; spending it on a draft that a colleague could have fixed in ten minutes wastes the most limited resource in the process.
Then wide async review with a deadline. The deadline matters: a doc circulated without one is reviewed by nobody, because there is never a moment when it is due. Reviewers comment in the document, and the author responds in writing — resolving, disagreeing with a reason, or amending. Most objections are settled here, and this is the process working as designed. The written exchange is also higher quality than its verbal equivalent, because the response has to survive being read twice.
A meeting happens only for what async review could not resolve — usually a genuine disagreement between two reasonable positions, which is precisely what synchronous discussion is good at and written comments are bad at. The meeting's agenda is the unresolved comment list. A design review meeting that walks the document from the top is a meeting where nobody read it, and the correct response is to end it and reschedule rather than to convert an hour of senior attention into a read-aloud.
Finally the decision, and this is the step most often dropped. Someone named decides, on a date, and the decision plus its reasoning goes into a durable log — an ADR, a decision registry, whatever is searchable and outlives the doc. The document itself then becomes historical: it is the record of the argument, not a description of the system, and it must never be edited into pretending it always said what was built. When reality later disagrees — and it will — the honest move is a new entry that supersedes the old, preserving the fact that the original reasoning was made in good faith with the information available. A decision log that has been retroactively made correct is a log that teaches nothing.