Writing Design Docs That Get Read

By Michael Samuel Naeem · January 13, 2025 · 5 min read

The rewrite that took three months because nobody agreed on the approach. The migration that broke production because the team didn't know about the edge case in module four. Both preventable with a design doc that took four hours to write and got reviewed before a line of code shipped. Design docs aren't bureaucracy — they're the cheapest place to find flaws in an architecture.

Template that works

# Title: [Verb] [System] [Goal]
# Author: [name] | Status: Draft / In Review / Approved
# Reviewers: [names] | Date: YYYY-MM-DD

## Problem
[2-3 paragraphs: what's broken or missing, why now, what happens if we don't solve it]

## Goals / Non-Goals
**Goals:**
- [Measurable outcome 1]
- [Measurable outcome 2]

**Non-Goals:**
- [Explicitly out of scope — prevents scope creep in review]

## Current State
[How it works today. Diagram if helpful. Link to relevant code.]

## Proposed Solution
[Your recommendation. Architecture diagram. Key data flows.]

## Alternatives Considered
| Option | Pros | Cons | Why rejected |
|--------|------|------|-------------|
| A: ... | ... | ... | ... |
| B: ... | ... | ... | Selected |

## Detailed Design
[APIs, schema changes, sequence diagrams, error handling, migration plan]

## Rollout Plan
[Phases, feature flags, rollback strategy, monitoring]

## Open Questions
- [ ] [Question needing reviewer input]
- [ ] [Decision deferred to implementation]

## Appendix
[Performance estimates, detailed schemas, research links]

Writing for skimmers

Reviewers spend 10–15 minutes. Front-load the decision:

1. Title tells them the topic
2. Problem + Proposed Solution in the first page
3. Alternatives show you considered options (builds trust)
4. Open Questions tell them where to focus feedback

Use diagrams for anything with more than two components. A 5-box diagram replaces three paragraphs and survives skimming.

Options and tradeoffs

Never present one option. Present at least two:

### Option A: Event-driven sync via Kafka
- Pro: Decoupled, scales independently
- Con: New infrastructure, operational complexity
- Effort: 4 weeks

### Option B: Direct API calls with retry
- Pro: Simple, uses existing infra
- Con: Tight coupling, cascading failures
- Effort: 1 week

### Recommendation: Option A
The coupling risk in Option B has caused two incidents this quarter.
The 3-week investment pays for itself in reduced on-call burden.

Reviewers trust recommendations backed by rejected alternatives more than single-option proposals.

Getting useful feedback

Share the doc 24–48 hours before the review meeting. Ask specific questions:

## Questions for reviewers
1. Is the rollback plan sufficient for the schema migration?
2. Does the caching strategy handle cache invalidation on write?
3. Are we missing a compliance requirement for PII handling?

Vague "please review" gets vague "looks good." Specific questions get specific answers.

Common mistakes

ADR for the record

After approval, capture the decision:

# ADR-042: Use Kafka for order event sync

## Status: Accepted

## Context
Order service and warehouse service need reliable event delivery...

## Decision
Use Kafka with transactional outbox pattern.

## Consequences
+ Reliable delivery, existing Kafka ops team
- 4 week implementation, new topic to monitor

ADRs live in the repo (docs/adr/042-kafka-order-sync.md) — searchable forever.

When not to write a doc

• Following an established pattern ("add CRUD endpoint like the other 12")
• Time-sensitive hotfix (write retro doc after)
• Exploratory spike (write findings, not a proposal)

My threshold: if I'd want input from someone outside the immediate task, it gets a doc.

Review process that actually works

A design doc without a review ritual becomes shelfware:

1. Author posts — link in #eng-design, tag 2–3 required reviewers + optional stakeholders
2. 48-hour comment window — async comments on specific sections, not meeting ambush
3. Office hour — optional 30-min sync for unresolved threads only
4. Decision recorded — Approved / Approved with changes / Needs revision
5. ADR filed — within 24h of approval

Required reviewers should include someone who will operate the system, not only peers who wrote similar code. SRE rejection at design time beats production surprise at launch.

Sizing docs to scope

Oversized docs don't get read. If you're past 15 pages, split into "overview" plus linked deep-dives per component. The overview doc is what executives and adjacent teams read.

Stakeholder-specific sections

Add a short section per audience — same doc, different entry points:

• Product: user impact, rollout timeline, feature flags
• Security: threat model, data flows, auth changes
• Legal/compliance: PII handling, retention, audit requirements
• Support: customer-visible changes, rollback user experience

One paragraph each prevents the "legal found out at launch" failure mode.

Post-implementation accountability

Link the implementation PR to the design doc. After ship, add a "What we learned" section:

• Estimates vs actuals
• Deviations from plan and why
• Metrics to watch first 30 days

This closes the loop for the next engineer writing a similar doc. Pair with running effective meetings — design review meetings should review, not discover.

Production checklist

• Problem statement written before proposed solution
• At least two alternatives with rejection reasons
• Non-goals section prevents scope creep in review
• ADR filed within 24h of approval
• Post-implementation "what we learned" section added after ship

Resources

• Google design doc guide (internal, leaked versions widely referenced)
• Architecture Decision Records (Nygard)
• StaffEng — Writing and Communication
• RFC process (IETF model adapted for teams)
• Markdown diagram tools (Mermaid)