A Simple but Powerful Tool to Record Your Architectural Decisions

Tanmay Deshpande
May 20, 2018 · 3 min read
Image for post
Image for post
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.

Image for post
Image for post
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.

Image for post
Image for post

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 Tech Writer | Distributed Systems | Cloud | Programming | Cyber Security | Software Architecture | Artificial Intelligence

Better Programming

Advice for programmers.

Tanmay Deshpande

Written by

Avid Tech Writer | Distributed Systems | Cloud | Programming | Cyber Security | Software Architecture | Artificial Intelligence

Better Programming

Advice for programmers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store