ADRs
What is an ADR
ADR stands for Architecture Decision Record.
From the ADR GitHub organization's home page:
An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture and quality. An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM), but ADR usage can be extended to design and other decisions (“any decision record”).
Why ADRs
An ADR serves two purposes:
As a communication tool, it provides all the relevant information required to make an informed architecture decision.
It helps decision makers to make an informed architecture decision without having to go through the whole analysis themselves.
As a documentation tool, it provides a record of an architecture decision and of the information that was used to make that decision.
Whether after 3 months or 3 years, we have access to the underlying reasons for why a particular architecture decision was made.
When should I write an ADR
As often as possible
ADRs should be easy to write. Whenever you are faced with an architecture decision, you should be able to:
- express the issue succinctly
- identify relevant solutions
- evaluate each solution's benefits (pros) and drawbacks (cons)
- come up with a recommendation
If you are unable to do this, then your AD is likely to be wrong. The ADR merely formalizes these questions and your answers in writing.
In fact, writing an ADR during your analysis is likely to strengthen your analysis. Often, unverbalized thoughts feel a lot more logical and consistent than they really. Having to verbalize them (it write them down) will force you to check their logic and consistency.
As early as possible
You should write your ADR before the decision is made, during your analysis, and as early as possible during the analysis phase. Consider your ADR as a working document: you create it when you realize you face an architecture decision, and fill it up gradually as you work through the relevant questions, and evaluate the relevant solutions.
After the fact, the ADR becomes purely documentation, and nobody likes writing documentation (and it's always done badly).
The primary purpose of an ADR is to communicate your analysis to others. It should be kept up to date with whatever stage your analysis is at. If you are interrupted, the task can be handed over to a colleague who will complete the analysis and the ADR, without having to redo parts of the analysis already done by you.
It also helps other stakeholders (supervisor, peers, customer) to review, if they wish, your ADR and provide corrections or suggestions.
ADR as deliverable
ADRs are accepted as deliverables, but only if they are complete, ie, they MUST include:
- a proposed solution
- a list of all relevant alternative solutions, properly evaluated
- all information necessary to make an informed decision
To be accepted as a deliverable, the ADR status must be changed to Pending.
Where should I store my ADR
ADR should be stored in the project's documentation repository. ADRs are simply text documents, so they can go anywhere. However, it is best for them to be stored in a centralized repository, with collaborative and versioning features, so that everyone knows where they are and can find them easily; others can collaborate with you on the document; and it's easy to see who authored it, what are each author's contributions, and changes to the document over time.
Typically, ADRs are stored in the project's wiki (Notion, Outline), or even in the source code repo itself. ADRs can also be Google Docs.
The precise organization of ADRs (folders, sub-folders, etc.) will depend on the project. The main goal is that a particular ADR should be easy to find when needed.
ADR format
An ADR is a text document that follows a simple logical structure:
- Title, date, name of author(s)
- What is the issue
- what is the proposed solution
- what is the status of the decision
- what is the context/background/details that lead to the proposed solution
Unless using a specific platform (Notion, Google Docs), ADRs should be written in markdown format.
Title
The title MUST be short and express in a concise and accurate manner what is the issue being decided.
The title MUST NOT include the word ADR.
Date
Format: dd MMM|MMMM yyyy
Author(s)
Who wrote the ADR.
Only include the primary author(s).
Status
Indicates the status of the Architecture Decision.
It can be one of the following:
| Status | Description |
|---|---|
| Draft | ADR is being drafted; not ready for review or discussion |
| Pending | ADR is ready for review and discussion. According to its author(s), it provides all the information relevant to the issue being decided |
| Approved | Proposed solution has been approved. The ADR should not be modified after this point. |
| Rejected | Proposed solution has been rejected. The ADR may be modified and resubmitted. It should record the fact that the initial solution was rejected. |
When creating your ADR, it should be in Draft status. Change the status to Pending when you feel the ADR is ready for review and discussion. It should be complete, ie it should include:
- a proposed solution
- a list of all relevant solutions, properly evaluated
- any information necessary to make an informed decision
An ADR is a deliverable only when it is in Pending status.
Issue
What is the issue being decided? What problem are you trying to solve?
This should be a short summary, just long enough to make the readers understand what you are trying to resolve.
If you need to provide further details, create a Context section further below.
Solution
What is your proposed solution? Provide enough details so that it is very clear what you intend to do and its implications.
If these details are already provided in a later section, then you can simply refer to that solution.
Context
An optional section in case you need to further explain the issue's context or background.
Solutions
A list of all relevant solutions that you evaluated.
For each solution, include a section using the following format:
Name of the solution
A description of the solution.
Pros
- ...
- ...
Cons
- ...
- ...
Consequences
- ...
- ...