ADR — Architecture Decision Record
Decision fatigue is real and it sucks.
When decisions aren’t clear, people feel jerked around.
For 8 years, I worked at an organization that was allergic to decisions. Rather, they’d make decisions and then weasel out of them when things got challenging.
From that experience, I came to believe that “disagree and commit” is a toxin — where leaders and managers aren’t required to commit the same contributors.
Sticking to a decision requires a form of agreement, line-in-the-sand, waypoint, etc.
For me, it started small with a folder of markdown files called decisions. It was a blame-free way for anyone to peer into past decisions, learn how we came to that decision, and determine if the place we found ourselves was inside or outside of what we had predicted.
Earlier this year, I learned that Shopify uses “decision logs” to unite their teams around decisions.
But how is a decision log tracked? What’s the format? How are changes superseded?
My directory of markdown files was pretty ad-hoc. And I didn’t get into the nitty-gritty of Shopify’s approach with Ryan.
Welcome Architecture Decision Records
I saw this tweet by Charity Majors and the term “decision record” hooked me.
Yeeesssss!! Lowkey obsessed with decision records/ADRs right now. If I were starting a new company (which I *am not,* and *will never*) I would be using these from day one.
— Charity Majors (@mipsytipsy) December 10, 2022
And not just for technical decisions, either. For any decision with a blast radius of >1 group. https://t.co/Zi4ndzSNA0
My usual beef with reference architectures is that they launder the creators' assumptions into "best practices" without helping you put your own needs in context.
— Forrest Brazeal (@forrestbrazeal) November 17, 2022
Turns out there's a cheat code to get past this problem, and the team that built "Emblem Giving" found it: pic.twitter.com/Y1IBIxmYYB
The Architecture Decision Record is a document format described by Michael Nygard. Each record requires a few pieces of information:
- publishDate
- decision
- status
- context
- consequences
Consequences is my favorite. Because, when the going gets tough, the tough start wining about the known consequences of their own decisions.
Money by mouth
I’m using the ADR structure on a number of projects — personal and professional, this year and next. In fact, I just committed my first decision record to this very site using the command line tool adr-tools!
I’ll let you know how it goes.
And if you’re using them, let me know how they’re working!