Architecture Decision Records

Software Development is part science and part art. Not unlike making a movie. But a software developer’s role is very different from a movie director’s in one important way: When a director makes the final cut and releases the movie to the audience, the movie is in its finished state. The director will have to live with whatever goofs slipped through during post production. A software, on the other hand, is never done. If a bug slipped through in this version, you can always fix it in the next version.

Which brings us to an interesting point: The developer that started working on a software may or may not be the same person that releases it into the wild. A lot of software projects go through a hand-off process, sometimes even multiple times. And anyone who has ever seen children play telephone has seen that every hand-off diminishes the quality of the message. This leads to a situation (more often than not) of a software team wondering why the original developers decided to do things in a certain way.

Enter Architecture Decision Records.

The goal of Architecture Decision Records (ADRs) is to capture the thinking process that went into making significant decisions regarding the architecture of the software. The idea was made popular by Michael Nygard’s blog post.

ADRs can be used to capture a technical problem, the various options considered, pros/cons of each option, and the final decision made along with the the reasoning.

It goes without saying that the developers making the ADR should be open and honest about their thought process - just like it is important for future teams reading the ADRs not to judge prior team’s decisions - but to understand the context and assumptions under which the decisions were made - and to be thankful for the prior team’s efforts in recording the ADRs.

Over the last few years, several templates have been proposed for capturing ADRs.

The one that I have settled is on called Markdown Any Decision Record or MADR for short.

MADR uses markdown syntax - something most developers are already be aware of. MADR has simple and easy to understand sections to capture the problem statement, decision drivers, various options considered, final decision - its consequences and so on.

MADR also recommends storing the ADRs alongside your project files (in a folder called /docs/decisions) and commit them to your git repo. Filenames are suggested to be of the format nnnn-title.md where nnnn is a running sequence of numbers starting from 0001. MADR dogfoods their own recommendation - so you can find their internal ADRs in their github repo adr/madr.

The one thing you want to be careful about, is when you change a decision - do not edit an ADR - instead mark it as superseded and link it to a new ADR.

If you are unsure about ADRs, just start using them. You can always refine your process. Remember, we are making software, not movies.