Part 5 of 7 · 3 min read
Writing decisions down
A short record keeps the reason alive after the people have moved on.
Think of a lab notebook. A result without the method is hard to trust or repeat. A decision without its reason is hard to defend or change.
FSA recommends the architecture decision record (ADR): a short text file, usually one or two pages, describing one architecture decision. It is kept in a document format such as Markdown, or on a wiki page.
Architecture decision record (ADR)
An ADR is a short document that records one architecture decision, its context, its justification and its consequences.
Example: "42. Use asynchronous messaging between the Order and Payment services. Status: Accepted."
The basic structure has five sections, and the book adds two more:
| Section | What it holds |
|---|---|
| Title | A numbered short phrase naming the decision |
| Status | Proposed, Accepted or Superseded (plus Request for Comments, with a deadline, when feedback is wanted) |
| Context | The forces at work and the alternatives considered |
| Decision | The choice, stated firmly, with the reason |
| Consequences | The good and bad effects, including trade-offs |
| Compliance (recommended) | How the decision will be checked, by hand or by an automatic test (a fitness function) |
| Notes (recommended) | Author, dates, edits |
Status and history. An accepted decision that is later changed is marked Superseded by the new one, and the new one says which it replaces. The book's example: ADR 42 chose asynchronous messaging between the Order and Payment services. Later, the Payment service moved, and ADR 68 chose REST. ADR 42 is "Superseded by 68" and ADR 68 is "Accepted, supersedes 42". The link avoids the later question "why not use messaging?".
Decision wording. The book prefers a firm voice, "we will use asynchronous messaging", to a weak one, "I think messaging would be the best choice", because the weak form does not even show that a decision was made.
Why the reason matters. The book tells of an old decision to use gRPC between two services. Years later, an architect who did not know why replaced it with messaging for looser coupling. Latency rose and upstream timeouts followed. The original reason was low latency, accepting tight coupling. A record would have prevented the change.
Consequences, with numbers. The book's example is posting a review asynchronously. It cut the response from 3,100 milliseconds to 25 milliseconds because the user waits only for the message to reach a queue. The cost is harder error handling, for instance when a review contains banned words. The record keeps both facts, so a later critic can see the trade-off was already weighed.
Who may approve. The Status section forces a talk about who can approve what. The book suggests three tests: cost, impact on other teams, and security. A decision above an agreed cost, or touching other teams or security, cannot be approved by the author alone.
A worked example (made up):
ADR 17. Use a queue for sending order emails
Status: Accepted
Context: Checkout waits for the email provider, which takes 1.2 s on average
and sometimes fails. Orders must never be lost.
Decision: We will put "send email" on a queue. A worker sends it.
Consequences: Checkout drops from 1.5 s to 0.3 s. Emails can arrive a few
seconds late. We need a dead letter queue and an alert for failed sends.
Compliance: A test fails the build if checkout code imports the email client.
Common mistake
Recording what was built but not why. The structure can be read from the code. The reasons and the rejected options cannot.
Check yourself:
- What does "Superseded by 68" tell a reader?
- Name two things the Consequences section should contain.