A practical overview on Architecture Decision Records (ADR)

I have been using ADRs for some years. In this article I’ll try to give an introduction, share my feedback, and encourage you to start writing them if you already don’t.Something about the architecture decisional processTaking architecture decisions is tough. It can be the result of a bunch of technical and non-technical evaluations, made of tricky balances between technology, cost, time, and stakeholders’ requests. There is almost never one single, optimal solution. Instead, there are many reasonable solutions, no true/false, only better/worse. The final decision may seem like a small thing, but a lot of work may have been required to come to that decision. For this reason, architectural decisions are usually considered “wicked problems”.Nevertheless, most teams comes to a decision verbally during meetings, and those decisions are sooner or later lost or forgotten. And all that remains is just the state of things.This is really a shame, because in a nutshell, the real value of a decision is what stated by the “ Second Law of Software Architecture “:Why is more important than how.If you are curious about the first law, I can only recommend you to get and read the great book Fundamentals of Software Architecture written by Mark Richards & Neal Ford.Before going deep into considerations and tips, it’s useful to clarify the discussion giving a quick definition:An ADR is simply a concise document that explainswhy something is going to be made this way.The structure of an ADRThis is a basic example of ADR template, in markdown format, as suggested by Michael Nygard.# Title## Date## StatusWhat is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?## ContextWhat is the issue that we're seeing that is motivating this decision or change?## DecisionWhat is the change that we're proposing and/or doing?## ConsequencesWhat becomes easier or more difficult to do because of this change?There are a lot of other templates, with different levels of complexity, but in my opinion it is better to keep it small and fast to read. And the Nygard template is perfect, according to me.If you want to see some real examples, you will find at the end of the article some links to pages with many detailed resources and examples.Every decision should have a unique code, usually in the filename and in the title, resulting in something like:ADR0001 — Use an SQS queue to manage outgoing emailsEvery ADR should explain one single decision, not many of them. It’s frequent to write multiple ADRs after a long analysis, but each one should have its own code and its own lifecycle, because in the future some of them will change status, while others will stay in accepted state.WHY ADRs are so importantNow that we know what’s an ADR, it’s important to understand deeply the advantages of the adoption of this framework.Tracking the knowledgeArchitecture decisions are pieces of knowledge, among the most important, in my opinion. People moves between teams and companies, and it’s important not to lose that knowledge when someone leaves the team. On the other side, when a new member joins the team, they will face exactly the same lack of knowledge, and for sure they will ask themselves: “Why the hell the system was designed in this way?”. We developers are opinionated guys, and an architecture decisions log can be a great way to share knowledge and prevent frustrations. When given to new team members it can be a really powerful document, whose reading can save days, during the onboarding process.Empowering the team cultureWriting down architecture decisions is the first fundamental step to make them first-class entities in the teamwork final result. It’s the most structured way to align officially the whole team about the work behind important decisions. If the team is big, it can reduce the distance between design and development. In this way everybody can understand decisions that otherwise, from the bottom, without an overall view, could seem incomprehensible. Tracking decisions is also something that contributes positively to the team culture, because between the lines it says “for this team the design counts”.A matter of responsibilityAs a software architect, or as a technical leader, or even as a team with a shared leadership, one of your most important responsibilities is taking these decisions. Not writing them down could dangerously suggest that things are happening without a reason, driven by pure istinct or worse randomly.Your decisions could have an impact for many years, even if you will leave the project. It’s a matter of professionality, seriousness, and respect for those who will deal with the system in the future. Also, in the future, the ability to go back to old decisions and understand why there were taken, has many advantages:You will have the possibility to remember details that for sure you will have forgotten.If the decision, seen from the new context, will still appear as a good decision, good news for your self-esteem. You have been forward-looking or at least you’re a lucky person.If it will seem a bad decision, well, you will have the possibility to go deep into it, and you will be able to make a valuable retrospective and understand what happened:Option 1: The context was completely different, and now you can say that in that context it was the best option, or at least a good one. You did your job well. You are a software engineer, not a fortune-teller.Option 2: The context is pretty much the same, but you are now able to consider other variables, that you missed in the past, and that change your point of view. You are growing, you have improved your judgement, your next decision will be more accurate.Option 3: The context is exactly the same, and at this point it’s official what was already clear to everybody: you made a mistake. Anyway, it was a difficult decision, and at least you have a document that shows that you did your best, you’re not just a fool. Learning from your mistake, you’re already a better professional now.Other indirect advantagesUsually inside an ADR are also documented, in a more or less detailed fashion, the findings from investigations explored but not implemented. Describing the option that you are identifying as the best one, it’s almost inevitable to explain also why the other options are not so good. This information can have a huge value in the future, but is frequently lost, because there are no evident and direct reasons to track a solution that seems inappropriate.Another last-but-not-least advantage is that writing down an important decision is a way to force ourselves to be objective and wise. No one would ever write something like “We do this because we want to play with that sexy technology”, but this is something that happens often. If you are a developer you know that it’s true.Is just-plain-text mandatory?In this field there are no absolute laws. If a decision involves a complex relation that could easily be described with a diagram, I think that it’s okay to add it. Anyway, this should be only considered as an option if strictly necessary to avoid confusion, because in most cases it’s not needed. It’s likely, on the contrary, that if you feel the need of a diagram there is something wrong. It’s a wake-up call that you are mixing more decisions into one.The lifecycle of an ADREvery decision should start from a draft version, usually in proposed status, then move to accepted or rejected, and so on.The document should be managed with an append-only approach. For sure it’s you can edit any part of the decision to fix a typo, but the only part of the document that should evolve is the STATUS paragraph. In fact, if the decision is no more relevant it should simply change its status to deprecated. If the context changes, a new ADR should be created, and the old one should move to status superseded.In my experience it’s useful to add cross links between ADRs. I’m used to create links both when the relation is direct (for example “Superseded by ADR0027”) and when there is simply some kind of relation between two decisions (the second one is a consequence of the first one). If you’ve ever used Jira or similar issue tracking tool you probably got the point.WHERE should ADRs be stored?I think that there is no right answer, it depends by the team culture. The most common solutions are:I think that there are pros and cons for each solution. By the way, this decision could be a good candidate as a subject for the first ADR… ;-)Store into a wikiIf you think that ADRs should be easily accessible to everyone in your team, including non-technical people, this is for sure the best option. In addition to that, having them into the wiki is good because it’s easy to link the ADR from other project documentation pages, without leaving the platform. In my opinion, this advantage is also the drawback, because puts the architectural decision in the field of “documentation”, which is not exactly the passion of each developer.Store in a git repositoryIf you want the developers to perceive ADRs as something important, using git is for sure a good starting point. Developers love code and love git, and in their mind the subliminal message is “if it goes into a repo it’s important”. Git is a great tool also to enable a collaborative management of the release process of a new ADR, leveraging pull requests for decisions in proposed state. There also some good command line tools that could work well to automate the process. I still haven’t tried them, because for the time being I have not felt the need, but it could be an interesting option in the future.There is an interesting win-win tool called log4brains, that can turn your markdown into a static website. It’s also integrated into MADR template. I haven’t had time to try them yet, but it’s in my backlog.WHO should be in charge of tracking ADRs?It doesn’t matter. This simply depends by the team and its culture. It could be a software architect, an entire team, a single developer, an ivory-tower architect, a technical leader, a senior developer or anyone else. What really matters is WHEN.WHEN should an ADR be created?When the decision will affect the work of the developersWhen the decision will be hardly reversibleWhen the decision is not obvious for the entire team (but pay attention, the team will change, sooner or later)Some final tipsWhile compiling the ADR, be very detailed about the context. This is the part that in the future could be more different, so it’s important not to be vague and not to assume anything. Describe the context with just facts, no opinions.Take your time thinking about the consequences, because it’s in that moment that the deepest reflections will come to light. And maybe you could even reconsider a decision that just before seemed really good.ReferencesThis is the fundamental article from Michael Nygard, published in 2011, that first introduced the idea of ADRs.The GitHub repo joelparkerhenderson/architecture-decision-record is a good source to get an overview of tools, articles and examples.The ADR GitHub organizationThe MADR templateTLDRIf you are responsible of architecture decisions and already don’t, start documenting them. Now. It’s fast, easy, not time-consuming, and there are tens of good reasons.Originally published at https://ctaverna.github.io on May 25, 2023.Level Up CodingThanks for being a part of our community! Before you go:👏 Clap for the story and follow the author 👉📰 View more content in the Level Up Coding publication💰 Free coding interview course ⇒ View Course🔔 Follow us: Twitter | LinkedIn | Newsletter🚀👉 Join the Level Up talent collective and find an amazing jobA practical overview on Architecture Decision Records (ADR) was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.