A couple of years ago I wrote a blog post on how to write a design document. This is a high-octane version of that blog post, refined for the era of short attention spans like the one I have now. In this post, I tell you what a design document is and what it isn’t, and give you a way that works for me to write one, only with fewer words. I’m doing this because I have a hard time getting anybody to read the previous one.

Maybe I should record a TikTok?

First: A design document is not the deliverable you care about. The deliverable you care about is shared understanding of a problem and alignment on a solution. The act of writing the document forces you to think clearly, surfaces what you don’t know, and gives your colleagues something concrete to react to.

Second: If you skip the document and jump straight to code, you might make all the same decisions — you’ll just make them implicitly, alone, and without the benefit of other people’s knowledge. Writing the document makes the decisions explicit and your reasoning reviewable. Who knows, you might learn something crucial that changes your decisions.

What’s in a design doc

Include all of the following, in whatever volume makes sense for the project:

1. Problem statement. What’s wrong, or what’s missing? What change in system behavior do you want? What does success look like? What problems are you explicitly not solving?

2. Background and research. What exists today and how does it work? What did you learn by investigating? Include data: scale, growth rates, failure modes, constraints. A reader who doesn’t live in this part of your system or codebase should be able to follow this.

3. Project values. What do you care about most? Resilience? Speed of delivery? Privacy? Cost? Simplicity? Write these down, because you will need them when you evaluate tradeoffs. Every interesting engineering decision involves giving up something to get something else. Without agreed-upon values, every tradeoff discussion devolves into opinion.

4. Options considered. What approaches did you evaluate? You don’t need an exhaustive list — two or three real contenders, with their tradeoffs stated honestly against your project values, is enough. If you only considered one option, say so and explain why.

5. Recommended solution, with rationale. What did you choose, and why? The rationale should trace back to the project values and the tradeoffs you surfaced. A reader should be able to disagree with a value and see exactly how that would change the conclusion.

6. Open questions. What don’t you know yet? What needs more research? What decisions are you deferring, and why? Admitting what you don’t know is a sign of rigor, not weakness.

How to write it: widen the circle

Don’t write the document in isolation and then present it to a crowd. Widen the conversation in stages:

Start with yourself. Take notes. Do research. Sketch the problem statement. This is where you discover what you don’t know.

Talk to one or two trusted people. Not to present a solution to them, but to learn. Explain the problem, listen to what they ask, take note of what you can’t answer. Their questions are more valuable than their opinions! This is the conversation that does the most for you. It’ll take that problem statement and put a fine edge on it.

Show it to domain experts. The people who know the systems you’re touching, the data you’re handling, the users you’re affecting. They will find the gaps in your research and the flaws in your assumptions. Revise including what you learn.

Show it to stakeholders before any public review. Nobody likes surprises. Give the people who care about the outcome a chance to read and react privately before you put it in front of the wider group. This isn’t politics — it’s respect for their perspective and time. A rule to live by: don’t surprise people in meetings.

Then open it up. By the time the document reaches a wider audience, it should have survived several rounds of honest questioning. The public discussion becomes productive because the obvious gaps are already filled.

Common failure modes

Jumping to the solution. The document opens with “we will use Tool X” and spends all its energy on implementation details. The reader can’t tell if Tool X is the right choice because the problem was never stated clearly enough to evaluate alternatives. Or, solution Y is described in detail, but the reader doesn’t know why solution Y is the one that got all the detail.

Missing the why. Every design choice has a reason; write down the reason. If you can’t articulate it, you haven’t finished thinking. “It seemed simpler” is a reason — write it down. “We didn’t consider alternatives” is also worth writing down, because it tells a reviewer where to push.

Not stating your values. Without project values, tradeoff discussions become arguments about personal preference. Two engineers can look at the same tradeoff and reach opposite conclusions — both reasonably — if they’re optimizing for different things. Make the optimization targets explicit.

Writing for approval instead of understanding. If the goal is to get the document approved with minimal friction, you’ll unconsciously hide the hard tradeoffs and open questions. If the goal is shared understanding, you’ll surface the difficult decisions. Writing for approval produces documents that look polished and collapse under scrutiny. Writing for understanding produces documents that look rough and hold up.

The inevitable recap

This is the part where I tell you what I just told you, only while swinging a big loud hammer.

The act of writing the document is more important than the document itself. Once you start implementation, the document will drift out of sync with reality; this is normal! What lasts is the shared understanding you and your team have because you worked through the problem together. You are all certain that you’re solving the right problem with the right tradeoffs. The shared understanding is what matters most.

And yes, this works just as well if your team is an agent. Don’t skip the part where you, the human, understand the problem.