A Simple but Powerful Tool to Record Your Architectural Decisions
From the moment I took over the role of technology architect, I’ve been wondering why certain decisions were made instead of other options.
Visio diagrams are great, but they’re nothing but pictures. They don’t tell you the story behind why certain arrows go a certain way and not the other way round.
ThoughtWorks Technology Radar
“We are a software company and a community of passionate, purpose-led individuals. We think disruptively to deliver technology to address our clients’ toughest challenges, all while seeking to revolutionize the IT industry and create positive social change.” — ThoughtWorks
In the Technology Radar, ThoughtWorks publishes news on what you should use, what you should keep doing, and what you could try.
ThoughtWorks talks about various:
While reading the techniques section, I noticed that ThoughtWorks recommends adoption of Lightweight Architecture Decision Records(LADR).
I didn’t know about LADR, so I started researching.
History of LADR
While researching LADR, I came across a very interesting article written by Michael Nygard. The article talks about having a technique to embed architecture documentation as part of code itself.
Quoting from the article:
Architecture for Agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins. — Michael Nygard
This is true. Agile is widely used, and there needs to be a defined process to capture all architectural decisions. Often, we end up creating large amounts of documentation which nobody likes to read.
As I read more, I found a better way to document your decisions.
ADRs can be documented in the source code repository itself. You can simply create ADRs as part of the Git repository.
For example, you can create this folder:
And add decisions to it as shown in the diagram below.
Content of the ADR
The content of the ADR can have the following sections:
- Title — Title of the decision record.
- Decision — The decision that was made. For instance, use Elasticsearch for an enterprise-wide search API.
- Status — Status can be proposed, accepted or superseded. If you make any decisions and you need to change them later, you can simply add a new record with the changed status.
- Context — What is the context of this decision? It is important to capture the full context of the decision so that the reader knows the reasons behind it.
- Consequences — In this section, you can add what would happen if this decision is made. It is important to list all consequences, both positive and negative.
The whole document needs to be one or two pages and not more than that. The idea here is to keep it light so people can read it.
Developers need to see the ADRs all the time as they should be aware of the reasons why they are building something.
This is not the only ADR template you can use. Many teams are using their own templates. You can find additional collections of ADR templates on GitHub.
As we grow more and more towards Agile-based development, we need to adopt techniques like this so we’re more efficient and agile in our architectural documentation as well.
Thanks for reading! If you have suggestions on documenting architectural decisions, leave a comment.