11 September 2018
By: Tomas Malmsten

Using Architecture Decision Records to document your architecture

Have you ever asked your self the question: "Why did we do it like this"? I have, many times, when I revisit places in the code. We make decisions on a daily basis on how to solve things, some bigger then others. At some point later we come back to it and can't recount why we thought it a good idea at the time. For smaller design decisions this is sometimes OK. But for things that affects our architecture we'd often like to know why.

For some time now there has been a pattern for this. It's called Architecture Decision Record. As far as I can tell Michael Nygard identified the pattern in 2011. The blog post can be found here. It has since come up on Thoughtworks Technology Radar and ended up in the adopt section.

The idea is pretty simple. You create a light weight document, like a markdownd file, which you store close to the source of the decision, in the code base. It is structured much as a pattern, with context, decision, status and consequences. Michael Nygard describes the format really nicely in his post, using the format itself. There are several other variants of the ADR format, and you should use one that fits your need.

Here are some useful links to resources on ADRs:

I introduced ADRs into our organisation a bit more then a year ago and it is providing us with a lot of value.

Tags: Architecture