π Architecture Decision Record
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.