Tanmay Deshpande
May 20, 2018 · 3 min read
Photo by Brooke Cagle on Unsplash

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

Whilst trying to solve this dilemma, I came across the latest edition of 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:

  1. Techniques
  2. Platforms
  3. Tools
  4. Languages & Frameworks

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.

Git Friendly

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.

ADR in GIT Repo

Content of the ADR

The content of the ADR can have the following sections:

  1. Title — Title of the decision record.
  2. Decision — The decision that was made. For instance, use Elasticsearch for an enterprise-wide search API.
  3. 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.
  4. 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.
  5. 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.

Sample ADR

Here is a sample ADR that you can use for your reference.

GitHub has more examples of ADRs for your reference.

ADR Templates

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.

Better Programming

Advice for programmers.

Tanmay Deshpande

Written by

Avid Technology Blogger, Author, Architect, Big Data, Cloud & IoT : More on - https://stuff.technology

Better Programming

Advice for programmers.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade