Writing it down before you build it

Two documents can describe the same system in the same detail, and one collects forty comments in a day while the other is opened by two people and closed again. The difference is almost never the writing. It is whether anything in the document is still open at the moment it is sent.

The frustration behind this is specific: you wrote the thing down, precisely because you were told to write things down, and the reward was silence — followed, four months later, by somebody objecting to a decision that had been sitting in section three the whole time.

Why most of them go unread#

It is tempting to blame the format, and the format is not the problem. Google’s own widely-circulated account of the practice is blunt about it: design docs are informal documents that do not follow a strict guideline for their content, and should be written in whatever form makes the most sense for the particular project. There is no template you are failing to fill in.

The same source gives the test that actually decides the matter, and it is about the situation rather than the document. Write one when the solution is ambiguous — and if it is not ambiguous, there is little value in going through the process at all. That second half is the one that gets skipped, and skipping it produces the commonest dead document there is: a careful description of an approach nobody was going to argue with, written because the process asked for a document.

Read against that test, an unread doc is usually being honest. Nobody commented because there was nothing to comment on. The decisions had already been taken — in a conversation, in a spike, in the fact that the ticket was already estimated — and what was circulated was a report of them. Google’s write-up names this failure directly: a doc that has become an implementation manual, with no analysis of trade-offs, has stopped being a design doc regardless of how long it is.

What the document is actually for#

The purpose is to make disagreement cheap while it is still cheap. Everything else it does — onboarding a new person, settling an argument later, giving a reviewer context — is a side effect of the same text, and none of those side effects justify the hours on their own.

The sections that account settles on are five: context and scope, as objective background facts; goals and non-goals; the actual design, given as an overview and then details, with the trade-offs made explicit; alternatives considered; and cross-cutting concerns such as security, privacy and observability. That is a reasonable spine, and it is worth noticing what it puts at the centre. Three of the five sections exist to state something other than the plan.

Length follows from the same logic rather than from ambition. The stated sweet spot for a larger project is ten to twenty pages, with mini design docs of one to three pages for incremental improvements. Most disappointing documents are the twenty-page version of a three-page question: everything in them is correct, the one contested paragraph is on page eleven, and the reader who could have caught the problem stopped at page four.

The two sections that do the work#

Non-goals. A goal is a promise, and readers treat it as one; a non-goal is a scope boundary, and readers treat it as an invitation to argue now rather than in three months. The useful distinction, and the one that gets muddled, is between something that is not a goal and something that will never happen. “Multi-region failover is not a goal of this design” is a statement about this quarter’s work. “This design makes multi-region failover impossible without replacing the storage layer” is a statement about the system, and it belongs in the trade-offs, in those words, because it is the sentence someone will want to have seen.

Alternatives considered. This is the section people fake, and a faked one is worse than an absent one, because it looks like diligence. The tell is an alternative rejected on a property nobody was weighing — “we did not use a graph database because the team has no experience with it” — which tells a reader nothing about whether the option was good. An alternative earns its place by being written up in the same currency as the chosen design: what it would have cost, what it would have bought, and the specific fact that made the difference. Written that way the section does something a decision cannot do on its own — it lets a reader who knows something you do not attack your reason rather than your conclusion.

The other half of getting comments is not in the document at all. A doc sent to a group with “comments welcome” belongs to nobody. A doc sent to three named people, each asked a different specific question, is three obligations. Naming who has to agree, before circulating, also settles the question the document will otherwise raise at the worst possible moment: whether silence from a particular team counted as consent.

Where it goes wrong#

The expensive failure is the document circulated after the code exists, and it is expensive precisely because it appears to go well.

The shape is always the same. A branch is most of the way there. The doc is written up from what was built, and sent for review because the process expects one. Comments arrive and they are all small — a naming question, a request for a diagram, a note about a missing metric — because everyone reading it can tell that the structural objections are no longer affordable and there is no point spending capital on them. The author reads the pattern as agreement with the design and disagreement about details, which is exactly backwards.

The bill arrives later, and it is not a technical one. There is now a document, with a review history, that appears to record a team’s consent to a decision that team never actually weighed. When the objection finally surfaces — usually when the design meets a case it was not shaped for — the disagreement is no longer about the system. It is about who agreed to what, and the document is on the wrong side of it.

The second failure is quieter: the doc that never closes. The discussion happens, the design changes twice in comment threads, the work ships, and the document is left as it was written, with its rejected alternatives and its open questions still phrased as open. A year later nobody can tell which parts describe the system and which describe a plan that was abandoned. That is the specific gap a decision record written where the code lives exists to close: the design doc is the argument while it is open, and the record is the one-page result once it is not, which is why the two are worth keeping separately rather than trying to make one document do both jobs.

Worth separating too, because they are easy to confuse: this is about a document other people read and argue with. Turning a vague request into work that is ready to start — the acceptance criteria, the seed data, the definition of done — is a different exercise with a different reader, and a ticket that is ready to build is not evidence that anybody agreed with the design behind it.