Back to patterns again. And in specific ADR or Architectural Decision Records or even Lightweight Architectural Decision Records. The reason I write about this now is that it strikes me that more people should know the pattern exists. I recently read a couple of meeting minutes. The person who has written them has written them very much in the style of ADRs. They describe a problem, a context and a suggested solution.

What struck me when I read the meeting minutes though was that the author was not aware of the ADR pattern, which prompted me to write a little article about it.

So, what is ADRs? Well, the pattern is pretty simple. And others have described it much better (links to follow). But in short it's a way to document a decisions of architectural significance in a structured and versioned manner. There are many different formats but they all share a couple of key things:

• Title: A short title describing the solution and problem that needs solving.
• Status: of the record, for example pending, under consideration, accepted, adopted, superseded. Or something else that fits your needs.
• Version: of this record, since a decision often is revisited as new knowledge becomes available and a new decision may be the result.
• Context: In what context does this decision and problem exist. This is important since some problems, seemingly alike, requires different solutions when the context is different.
• Decision: What was decided, what is the solution we are going forward with.
• Consequences: What are the consequences of this decision? Some are probably good (I'd hope so at least) but some may also be bad. It's good to have both noted down.

What is so striking is that in many projects and on many products I have worked with this documentation is what most developers, and other stakeholder, constantly complains about is missing. This is the place where you'd go and look when you start poking around in a code base and can't understand why on earth we made the decision to do it like this.

You can place your ADRs wherever you like. There is a strong push for keeping them in the source tree, close to where the decisions are implemented. I have found that this does not always work. Sometimes a decision is not applicable in just one place, it has consequences in several places. Then it may make more sense to keep such ADRs in a location that is easy to get to without having access to a specific code base.

There are also more and more tools available that supports ADRs of different formats. They can help, but are not a prerequisite to use ADRs.

So if you haven't come across ADRs yet, or if you've thought about it but not started to use it, I'd strongly advice you to get started. Just talk with your team and start in the small. You don't even need to get a permission from or talk to the "Architect"*. Although the "Architect"* may want to know and may even want to use it as well.

As promised, some links to more in depth information on ADRs:

• The github ADR organisations
• Michael Nygard's original blogpost on the topic
• Overview on variant of ADRs

You'll find a lot more links leading on from the above so I wont list them here.

*"Architect" as in Ivory Tower Architect