Lesson 6 · Writing
Design docs & decision records
Writing scales decisions. A good design doc is an argument, not a description.
As teams grow, decisions made in meetings are lost, re-litigated and misremembered. A design doc (or RFC) moves the debate into writing, where people in other time zones can contribute, reviewers can see the reasoning, and new joiners can learn why the system is the way it is. Its purpose is to get to a good decision quickly, not to document what you were going to build anyway.
A useful design doc states the problem and the goals, and — just as important — the non-goals. It proposes a design, then lists the alternatives considered and why they were rejected. It names the risks, the open questions, and how success will be measured. Reviewers should be named, with a date by which the decision will be made; without a deadline, a doc can collect comments forever.
An architecture decision record (ADR) is lighter: a short file in the repository recording one decision, its context, the options and the consequences. ADRs are immutable — when a decision changes, write a new one that supersedes the old. A year later, “why did we choose this?” has an answer, and the team stops re-arguing settled questions.
Picture it
A team has argued about event sourcing in three meetings without resolving it. The tech lead writes a four-page design doc: goals, non-goals, the proposal, two alternatives and a decision date ten days out. Comments surface a compliance constraint nobody had mentioned. The decision lands on day nine — a simpler outbox pattern — and is captured in an ADR that has since saved two more debates.
Key formulas & frameworks
- Design doc
- Problem · Goals · Non-goals · Proposal · Alternatives · Risks
- Review
- Named reviewers + a decision date
- ADR
- Context → Decision → Consequences (immutable, superseded)
- Purpose
- Reach a good decision, not describe the build
Practice
Score: 0 / 5
Go deeper
- How to write a design doc that gets a decision madeArticle · 6 min read
Up nextIncident communication & postmortems
Next lesson