The most plagiarised Architecture Decision Record blog on the internet.
Disclaimer: 99% of the content below have been taken from Spotify, Red Hat, Amazon and Joel Park Henderson. This post is intended to be a summary of ADRs for people who have no experience of them (like myself at the time of writing it).
Before I essentially hand this article of to the good folks at Spotify, Red Hat, Amazon and Joel Park Henderson. I’ll give a quick explanation of why I introduced Architecture Decision Records into our Software Engineering Process.
Last year I built a Rules Engine for automation and personalisation of marketing campaigns, I was the sole architect on the project and it was initially built by 3 engineers. As the project gained momentum more resources were quickly added to the project at the request of senior management.
Without the required documentation available at the time of the team expansion I had to spend most of my time walking engineers through their tickets and they were left unable to gain autonomy over their work.
We ended up with a double whammy where I as the lead had no time available to complete any development work and many of the other engineers were severely hindered by knowledge silos in the team.
Ok back to the professionally written / plagiarised content.
Why you should be using architecture decision records (ADR) to document your project
Documenting architectural decisions helps a project succeed by helping current and future contributors understand the reasons for doing things a certain way.
Agile projects often make decisions on the fly, unlike the old waterfall world, where a long requirement-engineering phase precedes the development process. Often enough, the why and how of the feature are kept in the decision-making developer’s brain. Newcomers to the project then are left to wonder why certain things are done in a certain way, making it hard for them to figure out and contribute, as the necessary knowledge is not readily available.
As the name ADR suggests, you use these records for making larger architectural decisions. They don’t serve as a glorified change log or replace (good) commit messages.
Components of an ADR:
- Number/Date: A unique increasing number and date that usually follows the ADR-nnnn pattern to help sort them from old to new
- Title: Indicates the content
- Context (Why): Describes the current situation and why you made this decision or thought it necessary — some variations explicitly break out an “alternatives covered” section to ensure all considerations get recorded
- Decision (What/How): Describes the what and how of the feature
- Status: Describes the status; note that ADRs can be superseded later by newer ADRs
- Consequences: Describes the effect of the decision, listing positive and negative aspects While decision records contain the “technical” decisions, they should also list non-functional ones.
Note: In my current team I have included an ‘Action Points’ section that contains the steps required to implement the feature.
The goal is for the engineer that writes the ADR is able to explain the changes needed to the product owner and other team members but also helps with estimating effort and helps with educating team members how different parts of the projects eco-system work together.
This works well with the current changes that we are using ADRs for but may not suit all use cases. The inclusion of an Action Points section was partly driven wanting to give engineers more autonomy in their work and designing solutions while ensuring consistency in a relatively young project.
(I actually wrote this part myself, props to me)
When should I write an ADR
An ADR should be written whenever a decision of significant impact is made; it is up to each team to align on what defines a significant impact. To get you started, below are a few scenarios with my mental model for determining when to write an ADR:
Backfilling decisions
Sometimes a decision was made, or an implicit standard forms naturally on its own, but because it was never documented, it’s not clear to everyone (especially new hires) that this decision exists. If a tree falls in a forest and no one is around to hear it, does it make a sound? Similarly, if a decision was made but it was never recorded, can it be a standard? One way to identify an undocumented decision is during Peer Review. The introduction of a competing code pattern or library could lead the reviewer to discover an undocumented decision. Below is my mental model for when to backfill an architecture decision:
- Do I have a problem? Yes
- Is there a blessed solution? Yes
- Is it documented? No
- Write an ADR!
Proposing large changes
Over the lifecycle of a system, you will have to make decisions that have a large impact on how it is designed, maintained, extended, and more. As requirements evolve, you may need to introduce a breaking change to your API, which would require a migration from your consumers. We have system design reviews, architecture reviews, and RFCs to facilitate agreements on an approach or implementation. When these processes run their course, how should we capture the decisions made? Below is my mental model for how to document these large changes:
- Do I have a problem? Yes
- Is there a blessed solution? No
- Do I have a solution? Yes
- Is it a big change? Yes
- Write an RFC!
- Did my RFC conclude with a solution? Yes
- Write an ADR!
(A RFC Template can be found at the bottom of this wiki)
Proposing small/no changes
In our day-to-day, we make small decisions that have little to no impact. The cost of undocumented decisions is hard to measure, but the effects usually include duplicated efforts (other engineers try to solve the same problems) or competing solutions (two third-party libraries that do the same thing). Enough small decisions can compound into a future problem that requires a large process or effort (ie. migration). Documenting these decisions doesn’t have to cost much. ADRs can be lightweight. Below is my mental model for working through this:
- Do I have a problem? Yes
- Is there a blessed solution? No
- Do I have a solution? Yes
- Is it a big change? No
- Write an ADR!
Let’s roll it up into a diagram!
When should I write an Architecture Decision Record? Almost always!
How the ADR Review process works
Every team member can create an ADR, but the team should establish a definition of ownership for an ADR. Each author who is the owner of an ADR should actively maintain and communicate the ADR content. To clarify this ownership, this guide refers to ADR authors as ADR owners in the following sections. Other team members can always contribute to an ADR. If the content of an ADR changes before the team accepts the ADR, the owner should approve these changes.
The following diagram illustrates the ADR creation, ownership, and adoption process.
After the team identifies an architectural decision and its owner, the ADR owner provides the ADR in the Proposed state at the beginning of the process. ADRs in the Proposed state are ready for review.
The ADR owner then initiates the review process for the ADR. The goal of the ADR review process is to decide whether the team accepts the ADR, determines that it needs rework, or rejects the ADR. The project team, including the owner, reviews the ADR. The review meeting should start with a dedicated time slot to read the ADR. On average, 10 to 15 minutes should be enough. During this time, each team member reads the document and adds comments and questions to flag unclear topics. After the review phase, the ADR owner reads out and discusses each comment with the team.
If the team finds action points to improve the ADR, the state of the ADR stays Proposed. The ADR owner formulates the actions, and, in collaboration with the team, adds an assignee to each action. Each team member can contribute and resolve the action points. It is the responsibility of the ADR owner to reschedule the review process.
The team can also decide to reject the ADR. In this case, the ADR owner adds a reason for the rejection to prevent future discussions on the same topic. The owner changes the ADR state to Rejected.
If the team approves the ADR, the owner adds a timestamp, version, and list of stakeholders. The owner then updates the state to Accepted.
Where should ADRs be stored
We should track ADRs in Github in the same repo as the code being changed. This will make it easy to track changes to the codebase over time.
My suggestion is to store ADRs in a wiki/adr directory inside the src directory.
Conclusion
This is me again. I had my first retro of the year with the team yesterday and the ADRs were mentioned as one of the main improvements in our way of working.
The ADRs that have been written so far have taken a few days to be completed and although this initially seemed long and may appear as time taken away from other work being completed for me it is confirmation that there are problems with knowledge silos in the team.
Our ADRs are quite short and can be read in a few seconds. I encourage the team to add diagrams where possible but don’t enforce and standards on how they should be drawn. On this point I should mention that I am working in a Data team and not an enterprise software company so this not be the case in every company.
If you’ve made it this far thanks for reading. This was primarily an exercise for myself but I hope you can take something away from this article.
