In this article, we’ll see how Architecture Decision Records aka ADRs help to document our project’s architecture changes. We’ll also learn how to create and manage the ADRs effectively.
One More Set of Documents! Why?
This is the right question indeed. Why one more set of documents? Don’t we have so many documents already in our projects? And, don’t we agree on how hard it is to keep the documents relevant all the time?
Well, I am with you here. Maintaining documents is not easy. However, anything related to software architecture is a trade-off, and so is one more set of documents. If the benefits outweigh the overhead, there is no harm in going for it.
Why Do We Need Architecture Decision Records?
Usually, architects create High Level and Low Level Design documents. However, these documents provide the early guidance for the project’s architecture. During software development lifecycle, developers and architects make many decisions that refine or change the initial architecture of the project. We often miss to document these decisions for one or other reason.
I am sure, you would have faced such situations in your projects as well. In the haste to deliver our tasks on time, we make some big or small decisions that affect the project’s architecture. Of course, everyone is aware of the decision at the time of decision-making and implementation, so there is no problem. The problem arises when after a few years someone raises the question – why have we done it this way?
This is where the Architecture Decision Records come to the rescue. When we have the architecture decisions documented, we can easily refer to them years after the decisions have been made. This not only brings more clarity and transparency to the application architecture but also helps new joiners in the project to understand things better.
What Is an Architecture Decision Record?
An ADR or Architecture Decision Record is a document that lets the team know the rationale behind an architectural decision. Furthermore, an ADR specifies the problem the decision addresses, the options considered, and the decision itself.
It doesn’t matter how you format the ADR, or where you maintain it. What matters is that it should be simple, to the point, and relevant.
What Does an ADR Look Like?
As we already discussed, the first thing that ADR should have is the problem statement, background, or context. So, let’s say we want to decide whether we should use a NoSQL database or a relational database. An ADR for this may look like the following:
Title:
ADR-001-Database of Choice for ABC Corp
Status:
Approved
Context:
We want to select the database for the ABC Corp project. The database should support all the functional and non-functional requirements for the project. The options we are considering for the databases are Oracle, a relational database, and MongoDB, a NoSQL database.
This decision is the outcome of task id, ABCCORP-1213.
Decision:
Given that the application mostly deals with transactional data, we’ll use Oracle as the database for ABC Corp. In the future, if the application grows and we also happen to deal with non-transactional data, we’ll revisit this decision.
Is There a Format for Writing Architecture Decision Records?
Yes, there are a few ADR templates available on the internet that you can easily find. The previous example is a simplified version of the template by Michael Nygard.
You can start with any of the available formats. However, you must apply the KISS (Keep It Simple Stupid) design principle here and adjust the ADR template based on what works best for you. Let me tell you why!
When I started using ADRs for my project, I started with a “simple” template. I had a status field with color-coded statuses, a field for the list of participants and approvers, and so on.
The team was enthusiastic and we followed the template for some time. However, after a few months, I noticed the resistance to following the template. Especially, the status field. Getting the ADR from draft to proposed and from proposed to approved was an overhead. Consequently, we changed the approach. We had a culture of making any decision as a team. So, we first decided on what to do and then we used to write an ADR for the decision that is already approved.
Now, the point is not about the status field. This may or may not apply to your project. Here, I want to emphasize that we should be flexible enough to ensure that the team writes ADRs without considering it an overhead.
When to Create an Architecture Decision Record?
Any architectural decision taken in the software development lifecycle can be recorded in an ADR.
For example, let us say, you are working on automating some test cases. The test framework, your project uses, is not able to take care of one of your requirements. Therefore, you research and create an ADR to propose a new test framework.
You can create an ADR in the analysis and design phase, during development, or even while fixing a defect.
How to Manage Architecture Decision Records?
As we already discussed, an ADR should not be an overhead to write. However, it is also important that you should be able to reference an ADR whenever required. So, besides keeping it simple, it is also important to manage it well. Without any further ado, let’s see how to manage the ADRs.
Storing the Architecture Decision Records
First, decide where you want to keep the ADRs. You can use JIRA, SharePoint, or Confluence. Furthermore, we may even keep ADRs as markdown files in a code repository. Any approach is fine if someone going through your code can find the corresponding ADR.
Managing Changes in Architecture Decisions
Like everything, the software architecture also keeps changing. Therefore, we may make a decision that can render an ADR void.
Let’s take the database ADR example where we decided to use Oracle. Now, after a couple of years, let’s say we need to use a NoSQL database for some use cases. Here, we may go ahead and update the existing ADR. However, this is not the recommended approach.
An ADR should never change once approved and implemented. The correct way to take care of a change in ADR is to create a new ADR and change the status of the existing ADR from approved to deprecated or superseded as applicable.
Conclusion
In this article, we saw how we can use the ADRs to streamline the architectural decisions in our project. While we’ve discussed the benefits and use cases of an ADR, we also talked about the importance of keeping the ADR format simple.
If you have used ADRs in your project, please share your experience with my readers in the comments. Furthermore, If you liked this article, you can check my other articles related to technology, here.
Enjoy learning!