Let’s talk about Architecture Decision Records.
🤔 Why you should care about it
“Without understanding the rationale or consequences, [a new person coming on to a project] has only two choices: blindly accept the decision or blindly change it. It’s better to avoid either blind acceptance or blind reversal.” - Michael Nygard, former SVP, Enterprise Architecture & Platform Development, Sabre Corporation.
Engineering teams make multiple architectural decisions impacting infrastructure or software design in a project. Since making those decisions takes time and effort, teams can use ADRs to justify and communicate decisions to current and future stakeholders.
😫 Problem(s)
Newcomers don’t always understand past decisions —> When it happens, some will blindly accept the decision, even if it’s not valid anymore. In contrast, others can decide to change the decision even if it’s still valid.
It’s challenging to align multiple teams on impactful decisions —> In this case, in the spirit of speed, team leaders often don’t decide or make decisions without many justifications.
Ownership transition takes time —> When there’s a transfer of technology stack, the old project owners have to spend significant time explaining past decisions to the new owners.
😃 Solution
An Architecture Decision Record (ADR) is a short text file describing the context and consequences of an architecturally significant decision. It contains the following sections:
- Status, such as proposed, accepted, rejected, deprecated, superseded;
- Context: the issue motivating the decision or change;
- Decision: the change we’re proposing;
- Consequences: what becomes easier or more difficult to do because of this change.
💡 Key Concepts
Architecture Decision (AD) —> an infrastructure or software design choice that addresses a specific requirement.
Architecturally Significant Requirement (ARS) —> a requirement that has measurable effects on an infrastructure or a software system’s architecture.
Request for Comments (RFC) —> a peer-reviewed document to propose technical development or set standards that can lead to one or multiple ADRs if authors make decisions.
Open Decision Framework (ODF) —> a framework for making transparent, inclusive decisions in organisations that embrace open source principles.
😡 Detractors
” No one ever reads documentation.” —> This is true for large documents that team members rarely update. On the contrary, an ADR is a short, modular document that is easier to consume and update.
” ADRs are just glorified change logs.” —> ADRs are not replacements for (good) commit messages or existing change logs. They are beneficial when it comes to impactful or controversial architectural decisions.
📚 Top book
Documenting Software Architectures: Views and Beyond - Felix Bachmann, Len Bass, Paul C. Clements, David Garlan, James Ivers, Reed Little, Paulo Merson, Robert Nord, Judith A. Stafford
⚙️ Templates & Tools
Architecture decision record (ADR) - Joel Parker Henderson —> A collection of markdown templates converted to Markdown
The Markdown Any Decision Records - GitHub —> Lean ADRs to quickly document architectural decisions in code
adr-tools - Nat Pryce —> Bash scripts to manage ADRs in the Nygard format
📝 Content
Documenting Architecture Decisions - Michael Nygard, former SVP, Enterprise Architecture & Platform Development, Sabre Corporation —> The original essay on ADRs.
When Should I Write an Architecture Decision Record - Spotify engineering blog —> How Spotify uses ADRs.
Using architectural decision records to streamline technical decision-making for a software development project - Darius Kunce and Dominik Goby, Application Architects, AWS Professional Services —> A complete guide by AWS to create and use ADRs.
Companies Using RFCs or Design Docs and Examples of These - Gergely Orosz —> This article collects some openly available RFC templates and examples and a list of companies that use such a process.