A design doc is a short written plan for a piece of software, shared before you build it. It states the problem, the solution you propose, and the options you rejected. Its main job is to catch design mistakes while they're still cheap to fix: in a document, not in production code. As a new grad, you'll read many design docs before you write one, and knowing the shape helps you review them well.
When a design doc is worth writing#
A design doc costs time, so write one only when the decision needs it. Ask two questions: would a mistake be expensive, and do other people need to agree? The table shows how that plays out.
| Write a doc when... | Skip the doc when... |
|---|---|
| The work takes more than a few weeks | The change is small and easy to undo |
| Several teams or services are affected | The solution is obvious and nobody disagrees |
| You change a public API or data model | A prototype answers the question faster |
| The change is hard to reverse (e.g. a storage migration) | The doc would only repeat the code |
| There are real trade-offs to choose between | You fix a bug with a known cause |
If you're unsure, write a one-page version. A short doc that gets read beats a long doc that doesn't.
Standard sections#
Once you decide to write one, you don't have to invent the structure. Most design docs use the same core sections, grouped below into the problem, the solution and the delivery. Names vary by company, but the content is similar.
The problem#
- Context: what exists today and why it isn't enough. Give the reader the facts they need, and no more.
- Goals: what the design must achieve. Make each goal testable, for example "p99 latency under 200 ms".
- Non-goals: things a reader might expect but that you deliberately leave out. Non-goals stop scope creep and end many review arguments early.
The solution#
- Proposal: the design itself. Include the components, data flow, APIs and data model. Add a diagram here.
- Alternatives considered: the other options and why you rejected them. Include "do nothing" if it's a real option.
- Trade-offs: what the proposal costs you, for example more complexity, higher cost or weaker consistency.
Delivery#
- Risks: what can go wrong, and how you will reduce each risk.
- Rollout plan: how the change reaches production. Mention feature flags, canary releases, data migration and the rollback path.
- Testing plan: how you will prove the design works, including load tests if performance is a goal.
- Open questions: decisions you haven't made yet. Listing them invites reviewers to help.
If the proposal section feels familiar, that's because it follows the same steps as a system design interview. See What is system design for that process.
Writing tips#
Having the right sections is half the job; the other half is making them easy to read. Reviewers are busy, so write for a reader who has ten minutes. These habits make a doc fast to read and easy to challenge.
- Lead with the decision. Put a two-to-three sentence summary at the top. State what you propose and why.
- Use diagrams. One box-and-arrow diagram of the data flow often replaces several paragraphs.
- Use numbers. Write "10,000 writes per second at peak" instead of "high traffic". Numbers let reviewers check your reasoning.
- Keep it short. Many good docs are 3 to 10 pages. Move detail to an appendix.
- Show your reasoning, not only the result. Reviewers can only find a flaw if they can see the logic.
- Use plain words. Define each acronym the first time you use it.
If you can't write the summary in three sentences, the design probably isn't clear yet. Fix the design before you polish the doc.
The review process#
With a draft written, the next step is getting it reviewed. A design review collects feedback and ends with a clear decision. The usual flow has three stages.
- Async comments. Share the draft with reviewers and give them a deadline, often a few days. Reviewers leave comments in the document. Reply to each comment and resolve it, or move it to the open questions.
- Review meeting. Hold a meeting only for the points that comments did not settle. Some teams start the meeting with silent reading time, so that everyone has read the doc.
- Sign-off. The named approvers (often a tech lead and the owners of affected systems) approve the design. Record the decision and the approvers at the top of the doc.
Ask for reviews early. A rough draft with a clear problem statement gets better feedback than a polished doc that already looks final.
Keeping it updated#
Sign-off isn't the end of the doc's life. A design doc describes a plan, and plans change during implementation. An old doc that disagrees with the code misleads the next reader, so a few habits keep it honest.
- Add a status at the top: draft, in review, approved, implemented or abandoned.
- When the design changes in a significant way, update the doc and add a short changelog entry.
- After launch, add a link to the code and to any launch notes.
- If the doc becomes too old to fix, mark it obsolete and link to the replacement.
For small decisions that come up later, a short decision record is often a better fit than editing the full doc. See Decision Records and Trade-offs.
Key takeaways#
- Write a design doc when a mistake is expensive or many people must agree. Skip it for small, reversible changes.
- Goals and non-goals define the scope. Alternatives and trade-offs show that you thought about other options.
- Put the decision first, and use diagrams and numbers instead of vague words.
- Review in stages: async comments, a short meeting for open points, then a recorded sign-off.
- Keep the status current so that the doc never disagrees with the code without warning.