I see an ADR in my review queue. I open it, scroll past a diagram and two paragraphs of architecture history, and can't find the decision.
There might be a good idea in there. I want to know what it is before I start leaving comments on page four.
I had that kind of review in mind while reading Martin Fowler's article on Architecture Decision Records. He describes an ADR as a short document for one architecture decision. The team records the context and what they expect to happen because of the choice.
Fowler spends some time on the record part, but his point about writing caught me. The team gets a chance to find the holes and disagree before they start building it.
This is where I get involved as an EM. I can get the right people into the review and add context the author doesn't have. I need to keep my opinion from taking over the document.
I want the draft before the team agrees
If the team writes the ADR after the meeting where they made the call, I get a clean history of the answer. I miss the part where a reviewer could have improved it.
I want the engineer to open the ADR while the recommendation can change. The person who knows the service's failure modes may spot an assumption. The engineer who gets paged when the queue stops draining may have a different definition of "easy to operate."
I don't add half the company to the review. I find the people with context the author needs, then give them enough time to read it. They bring information. The engineer writing the ADR keeps the decision.
My title can end a technical discussion fast. It can teach the team to wait for my answer the next time. I ask questions and make sure we close the open threads. I don't hide a veto in comment forty-seven.
Give me the decision before the diagram
Fowler recommends putting the useful part first. I agree. I should know the call within the first few lines.
This is enough to get me started:
Status: Proposed
Decision: Keep the existing queue for the first release.
Context: The team needs scheduled retries without taking on another service.
Tradeoff: Recovery will be slower during a regional outage.
Revisit when: Retry volume passes 50,000 jobs per hour.
The benchmarks and diagrams can come next. So can the spike that ate most of Tuesday. I will read them if they help me check the call.
When the author keeps an ADR short, they have to choose which facts belong in the decision. That takes more work than dropping every research note into the file, but it saves each reviewer from doing the edit in their head.
One good option and two crimes isn't a tradeoff
I get suspicious when the recommendation wins on speed and cost while both alternatives look irresponsible.
The team gives something up with any useful architecture choice. We may keep a service we understand and accept slower recovery. We may add a datastore and give someone another thing to own at 2 a.m.
I want the ADR to name that cost. I want the real alternatives, not every idea someone pasted into Slack. An engineer reading it six months later should be able to see why we skipped the option that looks obvious by then.
I can add context the author doesn't have here. Another team may plan to touch the same service. We may have nobody to own the new datastore. The engineer needs those facts before making the call.
I spend my review time on the consequences
I look at the diagram, but I spend more time on what the change asks from the team.
Who owns the new service? Who gets paged? A database change may need a backfill. A new tool may leave the team learning it during an incident.
I want the ADR to name the work instead of letting it show up halfway through the build. The author doesn't need each answer in the first draft. If they write the question down, we can assign a spike or pull in someone who knows the system.
Fowler suggests writing down what would make the team reconsider. "Revisit when traffic increases" will start another argument about the word "increases." "Revisit at 50,000 jobs per hour" gives us a number to watch. We may pick the wrong number, but we wrote down the bet.
Leave the accepted ADR alone
Fowler uses three statuses: proposed, accepted, and superseded. Once the team accepts an ADR, he recommends leaving the file alone. If the team changes the decision, they write another ADR and link the two.
I like having the old call around with its bad assumptions and missing information. Cleaning it up after the fact makes us look smarter and makes the history less useful.
A choice that made sense in January can stop working in July. The second ADR should explain what changed. The first one should show what we knew in January.
A pull request can be the wrong room
I like keeping ADRs in the repository. The team can review Markdown beside the code and see each change.
That setup falls apart if someone outside engineering needs to weigh in and doesn't see the pull request. Fowler calls this out. I care more about getting the right person into the draft than keeping the whole process inside Git.
We can write the draft somewhere the reviewers use, then put the accepted ADR in docs/adr. Nobody gets a prize for a tidy folder that hid the decision from the person with the answer.
I try to leave a useful comment
"Have we thought about scale?" tells the author I have a concern. It gives them nothing to answer.
I would leave this instead:
The worker keeps retries in memory. What happens to in-flight jobs during a deploy, and does that failure change the recommendation?
The author can answer the question or change the recommendation. Then I can resolve the comment instead of starting another vague thread.
I want to close an ADR knowing the engineer made the call with the context we had. Months later, someone else should be able to open the file and understand why we chose the existing queue, including the part we knew would hurt.
I want enough in the file that we don't have to reconstruct the whole thing from Slack six months later.