Communication & Influence

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

Question 1

Q1.Why do good design docs include non-goals?

Question 2

Q2.When an architecture decision changes, you should edit the original ADR to reflect the new decision.

Question 3

Q3.A design doc has been open for comments for six weeks with no decision. What is most likely missing?

Question 4

Q4.Which section most helps a reader trust the proposal?

Question 5

Q5.Design docs are most valuable for decisions that are expensive to reverse.

Go deeper

Up nextIncident communication & postmortems

Next lesson