Architecture decision records (ADRs) are a lightweight method for documenting architecturally-significant decisions within a project’s source control system.
This style of documentation serves as a great example for how we can document decisions on our project, even if they are not architecturally-significant.
You can record significant decisions affecting the structure, dependencies, interfaces, techniques, or other aspects of your code within ADRs. They are kept within the project’s repository so they are easily accessible to developers, easily modifiable, and have revisions tracked. ADR records should be kept short (maximum of two pages) so they are easily digestible by developers.
You can, of course, repurpose the ADR concept as a general decision record and track other project-related details, such as team structure, development process, communication styles, coding standards, tooling, etc.
Table of Contents:
ADR Format
The typical ADR format summarizes decisions in five parts:
- Title
- Status (e.g. proposed, accepted, deprecated, superseded)
- Context (description of the situation leading to the decision)
- Decision
- Consequences (positive, negative, neutral)
We recommend using both a numeric identifier (e.g., ADR-0001) and a human readable name summarizing the decision.
Often, you will benefit from describing alternative approaches that were considered but rejected. You should also note why a given choice was rejected. This will prevent future developers from redoing work that you have already performed.
As a design evolves, it is common to have ADRs that relate to or supersede each other. You can add a “Related ADRs” section whenever appropriate, referencing other ADRs by ID, title, or a direct link.
A good length to target for an ADR is 1-3 pages (in essence, a memo). However, this does not mean that essential information should be left out. Although supplemental information can also be externalized and simply referenced from the ADR, allowing those who need the additional context to get it.
Using ADRs
- One ADR documents one significant decision.
- If a decision is reversed, amended, deprecated, or clarified, keep the corresponding ADR. Instead of deleting it, generate a new ADR, link the related decisions together, and mark the previous decision with a relevant status note.
- Create ADRs for significant proposals that require a decision by the team. If the proposal is rejected, the ADR itself can be marked as such.
By keeping a full history of decisions, we help developers see the evolution of our decisions through time and provide the context for each decision.
ADRs as an Alternative to Design Documentation
ADRs are, in our view, a sustainable alternative to more traditional detailed design documentation. T
ypically, design documentation begins to fail at some point as decisions outpace updating of the document. And once someone “forgets” to update the document, it is viewed as obsolete and never updated again.
ADRs do not have this problem. When a design change occurs, you can document the change and rationale in a new ADR, leaving the old one in place. The new ADR can indicate which decision(s) have been superseded. This also preserves the history of the design’s evolution and provides context as to why various changes to the design were made.
Using ADRs
We prefer to use the adr-tools project below, but you can also implement ADRs with a basic Markdown template. Feel fre to tweak the templates to suit your team’s needs.
adr-toolswill manage the ADR process for you- Markdown ADR Template
- We set up every project using
adr-toolsin our course Automating the Deployment of a Reusable Project Skeleton
Example ADRs
- Architecture Decision Records for the embvm-core project
- ADR-004: Video Streaming Without Delay from Burkhard Stubert’s article on ADRs
- joelparkerhenderson/architecture-decision-record contains templates and eample ADRs
Further Reading
- Documenting Architectural Decisions Within our Repositories
- Q&A: How We Document Software Projects discusses ADRs as one documentation tool we use
- Documenting Architecture Decisions by Michael Nygard
- Scaling the Practice of Architecture, Conversationally, by Andrew Harmel-Law, discusses Decision Records as a key supporting element for a scalable Architecture practice.
- Documenting Software Architectures: Views and Beyond, by Clements et al., discusses decision records. Some select quotes below.
- Rejected. Decision that does not hold in the current system; but we keep such decisions around as part of the system rationale (see subsumes in the next list).
- Obsolesced. Similar to rejected, but the decision was not explicitly rejected (in favor of another one, for example) but simply became “moot”—for example, as a result of some higher level restructuring.
- Episode 35: Better Built by Burkhard Stubert
ADRs were exactly what I needed! And even a bit more. I could use them for decisions about system architecture, team structure, development process – and any other decision.
After the interviews with the development teams and with their stakeholders, managers and executives, I would write down the important topics requiring a decision. I would describe the context, possible options, the consequences of the decision and my recommended decision.
The decision records (DRs) were available on the company’s intranet for everyone to read. So, everyone could comment on the recommended decision. In weekly meetings, a team of managers, architects, senior developers and me discussed the recommended decisions. We revised the records, decided some right away and deferred some to gather more information for next week’s meeting.
[…]
A big advantage of DRs is that they decouple creation, discussion and decision temporally. Everyone can think through the decision asynchronously. That leads to more constructive and respectful discussions than the fights in meetings. Jeff Bezos, Amazon’s founder, has made asynchronous communication and excellent preparation of meetings.
« Back to Glossary Index