Design Docs, RFCs and ADRs
Senior engineers drive technical decisions through writing. Learn when a design doc is worth it, a practical template, how to run a review that ends in a decision, and how architecture decision records keep the 'why' alive for future engineers.
🎯 What you'll learn
- When to write a design doc
- A practical design doc template
- Running a review to a decision
- Writing and superseding ADRs
📚 Before you start
Senior engineers drive decisions through writing. A design doc (or RFC) proposes a solution and invites review before code is written; an ADR (architecture decision record) captures a decision and its reasoning so future engineers know why. Interviewers ask how you make and communicate technical decisions; showing a writing culture is a strong senior signal.
1When to Write a Design Doc
Write one when the work is hard to reverse, spans several teams or services, takes more than a couple of weeks, or involves real trade-offs people may disagree on. Skip it for small, reversible changes: a PR description is enough.
2A Design Doc Template
| Section | Content |
|---|---|
| Context and problem | What's wrong today, who it affects, with data. |
| Goals and non-goals | What success looks like (measurable) and what's explicitly out of scope. |
| Proposal | The design: components, data model, APIs, diagrams. |
| Alternatives considered | At least two, with why they were rejected. The section reviewers read most closely. |
| Trade-offs and risks | What gets worse, failure modes, how you'll mitigate them. |
| Rollout and migration | Phases, feature flags, backfills, rollback plan. |
| Observability and operations | Metrics, alerts, dashboards, on-call impact. |
| Security and privacy | Data handled, access, threats. |
| Open questions | What you need reviewers to weigh in on. |
Keep it as short as the decision allows: two to six pages is typical.
3Running the Review
- Share an early one-page draft with one or two key people for direction.
- Circulate the full doc with a deadline for comments and name the required reviewers.
- Resolve comments in writing; hold a meeting only for the contested points.
- Record the decision and who made it. Silence is not consensus.
4Architecture Decision Records
An ADR is a short, immutable file in the repository (e.g. docs/adr/0007-use-postgres-for-orders.md):
# 7. Use PostgreSQL for the orders service
Status: Accepted (2026-03-14) # Proposed | Accepted | Superseded by ADR-12
## Context
Orders need multi-row transactions and ad-hoc reporting; the team knows SQL well.
## Decision
Use PostgreSQL 16 on the managed service, one database per service.
## Consequences
+ ACID transactions, mature tooling. − Horizontal write scaling needs sharding later.ADRs are never edited after acceptance; a new ADR supersedes an old one. That history answers "why on earth did we do this?" years later.
⚠️ Common Pitfalls
- Writing the doc after the code: the review becomes a rubber stamp.
- No alternatives, or straw-man alternatives.
- Novels: twenty pages nobody reads. Lead with the summary and decision.
- Endless review: no deadline, no decision-maker.
- Decisions lost in Slack: nobody can find why something was chosen.
📋 Quick Reference
Design doc when: hard to reverse · multi-team · > 2 weeks · real trade-offs
Template: context · goals/non-goals · proposal · ALTERNATIVES · trade-offs · rollout · ops · security · open questions
Review: early draft → circulate with deadline → resolve in writing → record decision + decider
ADR: short, in the repo, immutable; new ADRs supersede old ones🧠 Key takeaways
- Write a design doc for changes that are hard to reverse, multi-team, long, or contested.
- The alternatives considered section is what reviewers read most closely.
- Run reviews with a deadline and a named decider; record the decision.
- ADRs are short, live in the repo, and are superseded, never edited.
🛠️ Practice exercises
Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.
✅ Check yourself
Answer the questions — feedback is instant.