Loading introduction
Loading stats
Loading about
Loading posts
Loading article
Skip to content
Md Nayeem Hossain
Explorer
home.tsx
writing-design-docs-that-get-approved.md
writing-design-docs-that-get-approved.md
blog.json

// Leadership

Writing Design Docs That Get Read and Approved

A structure for design docs that busy reviewers actually read: problem, goals, non-goals, alternatives, risks and a rollback plan.

Md Nayeem HossainFeb 16, 20264 min read
🧭

Writing Design Docs That Get Read and Approved#

The most expensive bugs I have seen were not in code. They were in designs: a data model that could not support a requirement nobody asked about, an integration that assumed a third-party API worked differently than it did, a migration plan with no way back. All of them would have been caught by an hour of discussion before the first line of code.

A design document is how you have that discussion cheaply. Writing them well is one of the clearest differences between a mid-level and a senior engineer.

When to write one#

Not everything needs a design doc. I write one when a change:

  • Takes more than a couple of weeks of engineering effort.
  • Touches several teams or services.
  • Changes a data model, a public API or a core workflow.
  • Is hard to reverse, such as a migration or a new vendor.
  • Has several reasonable approaches and the choice is not obvious.

For smaller changes, a good pull request description is enough.

The structure I use#

1. Context and problem#

Start with why. Describe the problem, who has it and what it costs today — with numbers where possible. If reviewers do not agree on the problem, they will never agree on the solution.

Affiliates currently wait up to 7 days for payouts because finance processes them manually every Monday. Payout-related support tickets make up 34% of affiliate tickets.

2. Goals and non-goals#

Goals define success. Non-goals are just as important: they prevent scope creep and endless review comments about things you deliberately chose not to solve.

  • Goal: automated payouts processed within 24 hours.
  • Goal: no payout is ever sent twice.
  • Non-goal: supporting cryptocurrency payouts.
  • Non-goal: changing how commission is calculated.

3. Proposed design#

Explain the approach clearly enough that a reviewer could spot a flaw. Include a diagram of the components and data flow, the data model changes, the API changes and the key sequences. Describe the unhappy paths as carefully as the happy path: what happens when the payment provider times out, or a payout fails halfway?

4. Alternatives considered#

This section builds trust. Show that you explored other approaches and explain why you rejected them:

Batch payouts via nightly cron. Simpler, but still leaves up to 24 hours of delay and creates a single large failure point. Rejected in favor of event-driven processing.

A design doc without alternatives looks like a decision looking for approval, not a decision that was made carefully.

5. Risks and open questions#

Be honest about what could go wrong and what you do not know yet. Reviewers trust a doc that names its risks far more than one that claims to have none. List open questions explicitly, with who can answer them.

6. Rollout and rollback#

How will this reach production safely? Feature flags, phased rollout, data migration steps, monitoring and — critically — how to undo it if something goes wrong.

7. Operational concerns#

Security, privacy, performance, cost, monitoring and alerting. A short paragraph on each shows the design has been thought through beyond the code.

Write for skimmers#

Your reviewers are busy. Make the document easy to skim:

  • Put a short summary at the top: problem, proposal and the decision you need, in a few sentences.
  • Use headings, short paragraphs and diagrams.
  • Prefer concrete examples over abstract descriptions.
  • Keep it as short as it can be while still answering the important questions.

Running the review#

  • Share early. A rough draft reviewed by two people beats a polished document that arrives too late to change.
  • Name the reviewers and the decision needed, with a deadline.
  • Invite disagreement explicitly. "What would make this fail?" is a better prompt than "Any feedback?"
  • Resolve comments in writing, and record the final decision and its reasoning in the document.
  • Hold a meeting only for contested points, not to read the document aloud.

After approval#

The doc does not become useless after approval. Link it from the epic and from the code. Update it when the design changes significantly during implementation. Months later, when someone asks "why does this work like this?", the answer is already written down.

Conclusion#

A good design doc states the problem with evidence, defines goals and non-goals, explains the design including its failure modes, shows the alternatives you rejected, names its risks honestly and plans the rollout and rollback. Write it for busy readers, share it early, and keep the decision recorded. An hour spent writing it can save weeks of building the wrong thing.

#Design Docs#RFC#Engineering Process#Communication
OlderRate Limiting at Scale: Token Buckets, Sliding Windows and RedisNewer Building Resilient Systems: Timeouts, Retries and Circuit Breakers

Outline

  • Writing Design Docs That Get Read and Approved
  • When to write one
  • The structure I use
  • 1. Context and problem
  • 2. Goals and non-goals
  • 3. Proposed design
  • 4. Alternatives considered
  • 5. Risks and open questions
  • 6. Rollout and rollback
  • 7. Operational concerns
  • Write for skimmers
  • Running the review
  • After approval
  • Conclusion