Design Doc Review
Before building something significant, the author writes a short document: context and scope, goals and non-goals, the proposed design and the alternatives considered with their trade-offs. Close colleagues help iterate on it, then a wider group reviews it in comment threads. A live review meeting is used only when comment threads cannot settle a point.
Use for any significant plan, not just software, where mistakes are cheap to fix on paper and expensive to fix later.
Solves: Teams discover design problems after the work is built, because nobody outside the team saw the plan in time.
- 1
Step 1: The author writes the doc: context and scope, goals and non-goals, the design, alternatives considered and trade-offs (2-6 hours, author only).
- 2
Step 2: Quick iteration with two or three close colleagues to reach a stable first version (async, 1-3 days).
- 3
Step 3: Share with the wider review group and a deadline. Reviewers comment in threads (30-60 min each, async).
- 4
Step 4: The author answers every thread, changes the doc or explains why not.
- 5
Step 5: If threads stay unresolved, hold a short live review on those points only (30 min).
- 6
Step 6: Record the decision at the top of the doc and keep it updated if the plan changes during delivery.
- Non-goals matter as much as goals. They prevent long debates about things nobody intends to do.
- Ask for the most important feedback early and do not let a slow review block all progress.
- Keep reviews proportionate. A small change does not need a formal review meeting.
- Use the same structure for non-technical proposals such as programme designs or policy changes.