Design reviews: writing and evaluating architecture documents

Why design reviews matter

A design review is a structured conversation about a proposed change. Done well, it:

• Catches problems before they ship
• Spreads context across the team
• Documents the decision and its rationale
• Builds the author’s design judgement

Done badly, it:

• Becomes a rubber stamp
• Picks on the author instead of the design
• Generates noise without decision

This lesson covers how to write a design doc that drives a productive review, and how to run the review meeting itself.

Anatomy of an architecture document

A good architecture doc has these sections:

1. Context and goals

What is the problem? Why are we solving it now? What does success look like?

Bad: “We need to migrate to Ceph.” Good: “Our current NFS backend is at 80% capacity and lacks the snapshot granularity for our new backup policy. We’re proposing Ceph to gain per-VM snapshots and multi-site replication. Success means supporting 200 TB with 7-day snapshot retention and 4-hour replication to DR site.”

2. Non-goals

What is explicitly out of scope? This section prevents scope creep.

• “We will not migrate existing VMs in this phase”
• “We will not change the existing network topology”
• “Performance targets are limited to the existing VM workload profile”

3. Proposed design

The actual design. Use diagrams (sequence, component, data flow). Be concrete.

• Specific components and their responsibilities
• Specific data flows with edge cases
• Specific configuration choices (with rationale)

4. Alternatives considered

What else did you consider? Why didn’t you pick it? This is the most valuable section for reviewers.

5. Risks and mitigations

What could go wrong? How do you detect and respond?

• Risk: Ceph cluster rebuild after 3 OSD failures is slow
• Mitigation: maintain hot spares, document the rebuild procedure, monitor rebuild progress

6. Operational considerations

• Monitoring and alerting
• Backup and disaster recovery
• Capacity planning
• On-call impact

7. Cost and timeline

• One-time costs (hardware, software licences, training)
• Recurring costs (power, support contracts)
• Timeline (with milestones)

8. Open questions

What don’t you know yet? Be honest.

• “We don’t know the actual workload IOPS profile; we’ll measure during the pilot”
• “We haven’t decided between two enterprise support contracts; pricing pending”

Writing for reviewers

Reviewers have limited time. Optimise for skim-then-deep-dive:

• Headings should be self-contained: a reviewer reading just the headings should get the gist
• Diagrams before prose: a diagram is 1000 words
• TL;DR at the top: 3-5 sentences summary
• Decisions in bold: so reviewers can spot them
• Numbers, not adjectives: “10 Gbps link” beats “fast link”

The review meeting

A design review meeting has three phases:

flowchart LR
  A[Design doc<br/>submitted] --> B[Phase 1<br/>Walkthrough<br/>10-15 min]
  B --> C[Phase 2<br/>Discussion<br/>30-45 min]
  C --> D{Decision}
  D -->|Accepted| E[Proceed]
  D -->|Accepted with changes| F[Revise &amp; proceed]
  D -->|Revise| G[Rework]
  D -->|Rejected| H[Pivot]
  E --> I[Follow-up<br/>tracked]
  F --> I
  G --> A

Phase 1: Walkthrough (10-15 minutes)

The author walks through the doc, focusing on:

• Context and goals (why)
• Proposed design (what)
• Alternatives considered (why not the others)

Reviewers should hold questions for the discussion phase unless something is unclear.

Phase 2: Discussion (30-45 minutes)

Open discussion. The author’s job:

• Take notes — every comment, question, decision
• Don’t get defensive — “Good question, I’ll check that” beats “But…”
• Defer decisions that need more data (“Let me verify and come back”)

The reviewers’ job:

• Ask the hard questions
• Challenge assumptions
• Surface risks
• Suggest alternatives (kindly)

Phase 3: Decisions and follow-ups (5-10 minutes)

End the meeting with explicit outcomes:

• Accepted — proceed as designed
• Accepted with changes — proceed, with a list of changes to make
• Revise and resubmit — significant rework needed
• Rejected — fundamentally wrong approach

Evaluating a design

When you’re the reviewer, your job is to ask the questions the author hasn’t asked. Common frameworks:

The “five whys”

For each major design choice, ask “why” five times.

“Why Ceph?” “Because we need multi-site replication.” “Why does the business need that?” “Because the RTO for our tier-1 VMs is 1 hour, and our current setup can’t achieve it.” “Why is 1 hour the target?” “Because the customer SLA commits to it.” “What if we accept a 4-hour RTO and skip multi-site?” …

If the answer to “why” runs out before 5, the requirement might be soft.

The failure mode walk

For each component, ask:

• What happens if this fails?
• How do we detect it?
• How do we recover?
• What’s the blast radius?

If any answer is “we don’t know”, that’s a follow-up.

The “what changed” check

A design should explain what changes for the team, the user, and the operations:

• What does the on-call need to learn?
• What dashboards are new?
• What runbooks need updating?
• What’s the migration path?

If the design is silent on operations, it will hurt in production.

Capturing decisions

After the meeting, the author writes up:

• Decision (Accepted / Accepted with changes / etc.)
• Changes required (numbered list, with owners and due dates)
• Open questions still to resolve
• Date for follow-up review (if needed)

This writeup goes in the doc itself, or in the team’s decision log.

Common design review mistakes

Author is defensive

Reviews fail when the author takes feedback personally. The author should treat every comment as a gift; even bad comments reveal something about how the design is perceived.

Reviewers nitpick instead of asking big questions

A design review should focus on the 3-5 big things, not the 30 small things. Save nitpicking for the code review.

Meeting runs out of time

Cut the discussion early and schedule a follow-up. A partial decision is better than no decision.

Decision is unclear

If you walk out of the meeting unsure whether the design was approved, the meeting failed. Always close with an explicit outcome.

No follow-up

Reviews without follow-up are performative. The point is to change something — either the design or the team’s understanding.

Key takeaways

• A good architecture doc has: context, non-goals, design, alternatives, risks, operations, costs, open questions
• The review meeting has three phases: walkthrough, discussion, decision
• Always close with an explicit decision and follow-up actions
• Reviewers should ask the hard questions, not nitpick
• Capture decisions in a log for future reference

Knowledge check