Writing Effective Design Docs
A practical structure for design docs that get read, reviewed, and used to make decisions rather than filed away and forgotten.
A design doc is a tool for thinking and a tool for aligning people. Most bad ones fail at both: they describe the solution already chosen, bury the trade-offs, and run so long that nobody reads past page two. A good design doc lets a reader who was not in the room understand the problem, the options, and why you picked one, in about ten minutes.
Start with the problem, not the solution
The first section should be readable by someone outside your team. State the problem, who is affected, and what happens if nothing changes. If you cannot write this in one paragraph, you probably do not understand the problem yet.
Weak: "We will introduce Kafka for order events."
Strong: "Order status updates reach the warehouse system up to 15 minutes late because of nightly batch sync. This causes about 40 mis-shipments a week. We need updates delivered within 30 seconds."
Define goals and non-goals
Non-goals are the most underrated section. They stop scope creep and pre-empt review comments.
| Goals | Non-goals | |-------|-----------| | Status latency under 30 seconds at p99 | Replacing the warehouse system | | No loss of events during deploys | Real-time analytics on events | | Reuse existing Postgres and AWS accounts | Supporting third-party consumers in v1 |
Present real alternatives
Reviewers distrust a doc with one option. List at least two or three, including "do nothing" and the cheapest possible approach. For each, give a short description, pros, cons, and rough cost. Then state the recommendation and the specific reasons it wins against your stated goals.
A compact comparison keeps the doc honest:
| Option | Latency | Ops burden | Effort | |--------|---------|------------|--------| | Shorten batch interval | 1-2 min | Low | 2 days | | Outbox plus queue | Under 5 s | Medium | 3 weeks | | Full event streaming | Under 1 s | High | 3 months |
Cover the cross-cutting concerns
Include a short section on each of: security and privacy, failure modes, observability, migration and rollout, and cost. You do not need pages, only evidence you thought about them. A rollout plan with a rollback step is more convincing than a diagram with twelve boxes.
Use a simple template
Title, authors, reviewers, status, date
1. Context and problem
2. Goals and non-goals
3. Proposed design (one diagram, one data flow)
4. Alternatives considered
5. Risks, open questions
6. Rollout and rollback plan
7. Decision log (filled in after review)
Keep it to three to six pages. Link out to appendices for benchmarks and schemas.
Manage the review lifecycle
Share a draft early, when changes are still cheap. Name specific reviewers and say what you want from each: "Priya, please check the failure modes; Sam, the data model." Set a deadline for comments, typically three to five working days. Resolve disagreements in a call, then record the outcome in the doc rather than leaving it buried in comment threads.
After approval, mark the status as accepted and keep the doc. Six months later, when someone asks why you did not use a different approach, the alternatives section answers it. If reality diverges from the design, update the doc or mark it superseded.
Common failure modes
- Writing the doc after building the system, as justification.
- Diagrams without a legend or a stated level of abstraction.
- Open questions hidden in prose instead of listed explicitly.
- No owner for follow-up, so decisions stay unrecorded.
Key takeaways
- Lead with the problem and its measurable impact, not the technology.
- Write non-goals; they prevent most scope arguments.
- Compare real alternatives, including doing nothing.
- Cover failure modes, rollout, and rollback in a few lines each.
- Keep it short, review it early, and record the final decision.