ADR — What, When, How?
Definition:
An ADR (architecture decision record) is a document that tells you an architectural decision that was taken, the context in which it was taken and the consequences of that decision.
When it’s needed?
It’s usually needed when you know or you are, already working on a product that is pretty long. The main idea is eventually the developers, BAs, POs and all the others will change the product, leave the company, disappear and they will make their decisions with them. No one will be left in some years to tell the story of why some decision was taken. NO wiki and confluence does not help! In my experience I saw a lot of documentation written in this kind of platform, that was almost never maintained, and even if it was maintained (more or less), every piece of documentation was written in there, from why an epic was needed to a recording of a demo. You can imagine how big becomes “the documentation tree” after a few years.
You should start writing it, whenever a decision is taken that will have a medium to a big impact on the product. Each member should state his opinion in defining how big or small is a decision and anyone from the team should be able to make an ADR. It shouldn’t be the burden of the architect or the tech-lead.
Another good moment in which you can identify if you need an ADR is during the code review. If you got the question: “why did you do that?”, or if you as a reviewer do not understand why a decision was taken, you should get your answer and create an ADR.
Benefits?
Having this document, the new people that will be hired will understand why some decisions were taken, so they won’t start to refactor all over the place and make mistakes, the same mistakes that were done and fixed by the devs that worked before them on the same product. Basically, it will help a lot in your onboarding process also.
If the product is “moved” and the ownership is taken by another team, they will be able to learn fast why decisions were taken in such a manner. You won’t need to rely on a specific person, and you won’t need a lot of time for the “handover” of the product.
How it should look like?
Personally, I like to use the pattern with Title (which should also contain the date), Status, Context, Decision and Consequences. The pattern was “invented” by Michael Nygard and you can see his entire article here. I used status also since we documented even the decisions that were not accepted, after our investigations, so anyone who will want in the future to implement the same thing or change our app, to understand if we thought or not about a solution and if we did, why didn't we implement it.
Some examples?
I would suggest having a look in here. I found this URL last year and it was pretty self-describing with lots of examples and different patterns. Since the information is in there, I see no reason to duplicate it with my examples.
Tools?
Being a .Net developer, I’ve tried different .Net tools. The only one that I can say for sure that you should try is dotnet-adr, but to be honest last time when we used ADR in a product, we actually used simple Notepad++, with that template.
Where should it be kept?
As I previously mentioned, I do not believe in confluence or wiki for this kind of stuff. I prefer having the ADRs, in the repo, near the code. Of course, they won’t be taken into consideration on the builds and they won’t be deployed anywhere. These decisions should be known by devs and it’s only for devs, so it should be where they always look over, day by day, so…near the code.
Very big products have lots of technical documentation written by technical writers. I don’t say it’s a bad thing…I say only that, that bible full of information will be a pain for a dev that just got his hands on it for the first time.
Do I really need it?
Let’s say you have a simple app with a UI, an API and a database. Your product is a monolith and it was started by you, last week…or maybe you just jumped into this ship and the product started 5 years ago. Do you know why it’s a monolith? Maybe it was simpler, to do? Maybe another type of architecture was not needed? Or maybe in the future, the idea was to create a distributed monolith? Let’s move on to the other layers; it’s Vue.JS, but…why it’s not React, since you think it’s better, or why not Angular? If it’s angular, why did they use RXJs, was it really necessary, in the end, it’s another big npm package with a lot of dependencies and it’s not really fun when you need to update it. Let’s talk a little about the database, is it MSSQL. Why not Oracle or PostgreSQL? Why doesn’t it have a NoSQL DB? Wasn’t it a good idea to have CQRS and read from a faster database? Have the devs before you thought about that, or if it’s you that took that decision, are you sure that in the day after tomorrow, you’ll remember all the details why did you take this decision (to be 100% it’s still the right one)? Requirements change pretty fast and will impact your product.
Almost every obvious decision, in time, won’t be so obvious anymore, will be just…confusion.
