Owning projects
Running a design review
Pick reviewers on purpose, go async first, meet only for stuck threads, and record the decision so code review does not re-litigate it.
A design doc that nobody reviews is a diary. A review that never records a decision is a meeting series. The job is to get to an approved approach — or a clear rework — without burning a week of calendar.
Concept
Disagree-and-commit means you argued for A, the group chose B, and you implement B cleanly. Re-litigating B in code review after the doc was approved destroys trust.
Walking through a review
- Pick reviewers deliberately. Include people who will own the fallout: the on-call team, the adjacent service owners, someone senior enough to spot a bad abstraction. Copying "eng@" and hoping is not a review plan.
- Async first. Give 2–5 working days for comments depending on urgency. Reply in threads. Do not resolve comments by force of personality without addressing the concern.
- Meeting only for stuck threads. A review meeting should resolve open questions and record decisions — not re-read the doc aloud. Come with a list of unresolved comments.
- Record decisions. When the approach is approved, write a short ADR or a "Decisions" section with date and owners. Link it from the ticket and the PR description later.
As a junior you may co-author or write a one-pager. As an SDE2 you are expected to drive the doc for a multi-week feature: draft, solicit review, resolve threads, and send a crisp "approved — building" note.
In interviews, when you sketch a system, narrate the same structure — goals, non-goals, alternatives, trade-offs — even without a document. That is what system design interviews reward.
Common mistakes
- Unresolved comments. Shipping while threads are red means you did not actually decide.
- Orphan docs. Approved design with no link from the epic, the README, or the ADR index — the next owner will rediscover the same debates.
- Re-fighting the design in the PR. If the doc chose B, the PR implements B. New facts can reopen it; preference cannot.
Check yourself
Three comment threads are still open and launch is Friday. What do you do?
Meet to resolve those threads, record the decisions, and only then start the expensive work.
The group picked read replicas. You wanted cache-aside. The first PR adds Redis anyway. What broke?
Disagree-and-commit. Implement the approved option, or reopen the doc with new evidence — do not silently switch in the diff.
Key takeaways
- Choose reviewers who will live with the fallout, not a blanket "eng@" ping.
- Async first; meet only to unstick; write the decision down.
- Link the approved design from the ticket and later PRs.
- After approval, implement the chosen option. Reopen with facts, not taste.
Further learning
Pair this with estimation and planning: the design names what and why; the plan names when and in what order.
A short talk on what belongs in a design document:
Related
Design docs and RFCs
Writing design docs that get to a good decision quickly — structure, alternatives, review, and when a one-pager is enough.
Writing design docs for reviewers
Lead with the decision on the first screen. Support it with diagrams and numbers. Ask for scrutiny, not applause.
Written and verbal communication
Lead with the point, write for skimmers, and adjust depth for engineers, PMs and executives.