⚡ Tl;dr
Architecture decision records (ADRs) are short text descriptions documenting architecturally significant decisions during the software development lifecycle. They capture high-level decisions that may not always be obvious from code or infrastructure. ADRs include important context for each decision, such as reasoning, consequences and tradeoffs.
ADRs can be thought of as an immutable list of decisions over time. Each time a new decision is made and accepted by the team it gets appended to the end of the timeline with a timestamp. Newly created ADRs supersede previous ones and can be deprecated when they’re no longer relevant.
If you want ADRs to be easily accessible to everyone on your team (including non-technical people) they can be stored in wiki tools such as Confluence or Notion. Checking ADRs into source control is also very powerful and provides all the benefits of Git, such as pull requests, version history and blame.
😮 The benefits of ADRs
Align teams on important decisions: ADRs can be published in a place accessible to everyone on the team, making it easy to communicate and align on important decisions.
Persist important decisions long-term: Details about decisions are easily lost when people move between teams or companies, and ADRs ensure they are persisted long-term.
Context of decisions for new team members: ADRs give new team members valuable learning about the decisions and tradeoffs that were made before they joined the team.
Document decisions that aren’t implemented: Findings from investigations explored but not implemented are just as important to document as ADRs in case they’re revisited later.
📝 How to write an ADR
ADRs can be customized to include the information you need, but there are standard templates, such as one created by Michael Nygard.
Title: A descriptive title that’s usually included in the file or document name.
Status: Current status of the ADR, for example: proposed, accepted, rejected, deprecated, superseded.
Context: The motivation or problem that led to decisions being made and any context needed to understand it.
Decision: Details and specifics about the change being proposed.
Consequences: Any positive or negative effects this decision has on other parts of the architecture.
ADRs can also be formatted similarly to user stories, as written out below.
In the context of <use case/user story u>, facing <concern c> we decided for <option o> to achieve <quality q>, accepting <downside d>.
🔨 Tooling for ADRs
There are a few tools available for creating, viewing and managing your architecture decision records.
adr-manager - Web-based application for creating and managing ADRs using Markdown stored in your GitHub repository.
adr-viewer - Show off your ADRs on a web page, either as a local web server or generated static content.
ADR templates - Collection of example ADR templates maintained by Joel Henderson.
Loqbooq - Web and Slack-based decision logs inspired by ADRs.
Log4Brains - Log ADRs from your IDE and publish them automatically as a static website.
🏁 To wrap up
Most teams make architecture decisions verbally in meetings that are easily lost or forgotten about. Documenting these important decisions as ADRs is something your future self and teammates will be grateful for!
Check out adr.github.io for information on ADRs.
Stay chill 🧊
