TL;DR

We realized that there has to a better way to record past decisions made on a project. Clubhouse and Git are limited when it comes to this. ADR offers a better understanding of why something needed to be changed, when it happened, what options were available, how it was implemented.

Our workflow

In most of the cases when we start a new project there are a few things that get set-up.

• Each project will have a folder in OneDrive or Dropbox structured in a conventional way
• The project has a Git repository
• A Clubhouse workspace is set.

Other things are also done, password storage, contact details linked with the project, and so on, but that is not relevant for this article.

After that we have Clubhouse details set, stories added, epics created, milestones set and sprints.

Between Clubhouse and Git, there is enough control to see what happened or needs to be done, who did something and the immediate changes of files. If you also use version control on your app it’s even better, this way you can see what is new from version to version and follow the pull request (usually from dev to production or staging).

The issue

While all that sounds good, there still is a part that is left behind.

For example, you decide to change the payment gateway on your app. In order to have this change, there was a discussion that started for a reason (context), there were some options, a decision was made to go with one of the options, someone took that decision at a certain point in time, that decision has some consequences that you understood.

In the Clubhouse + Git setup you can’t catch all these details. Replace Clubhouse with any project management tool, it’s still the same.

Another example: you added an extra mandatory field in the registration form.
Why did you need that?
What other options did you have?
What decision was made?
When did it happen?
What consequences came from this?
Who was involved in the decision making?

ADR to the rescue

You might’ve already noticed that there is a pattern in the above examples and that will be present in the ADR structure.

What is an ADR?

Architecture decision record (ADR) is a document that will capture an important architectural decision in your project.

This document has some different structure options, but they all include the same elements.

• Context (*)
• Date (*)
• Status (*)
• Options
• Decision (*)
• Consequences (*)
• People involved

(*) – mandatory

Why use ADR?

It’s a good way to keep track of changes and put them in context.
Might not seem that important at the moment, but it will be really helpful when you came back to a project 3 months later and you can’t remember why those changes were made in the first place.

It will also provide insightful information for the people that might come after you to work on the project or for new team members. Having a quick scan over the ADR folder and see why some things are the way they are it’s good way to get up to speed with what happened.

ADR structure

We decided to create an ADR structure to use in your projects.
At the project parent level, we have a docs directory that includes an adr folder.
In that adr folder we create files with a certain name structure 0001-ADRNameDescriptive.md.
Each ADR has a certain file structure.

You can find all these details in our ADR structure repository + some VSCode snippets for ADR.

Final thoughts and ADR example

We literally stumbled upon the idea of ADRs. I didn’t know what you search for in order to find this. It was a tweet that came up and was mentioning ADRs and from there I just connected the dots, did some research, and found out about this way of keeping track of important architectural decisions.

The repository that we linked above has more information, structure, links to external articles about ADR and it also includes some VSCode snippets for ADR.

Give it a try in one of your projects. It might seem like some extra work, but it’s worth it in the long run.