TECH | Architecture decision record (english version)
Architecture Decision Records (ADR) is a little-known technique in the living documentation palette, it centralizes and makes explicit a set of architectural decisions made over time, capturing the context and their possible alternatives. It complements the documentation very well with the code when these decisions concern the evolutionary architecture of your project.
An ADR1 can be local (within a component), or global (within an IT department).
- Why did we choose to use Hibernate?
- Why did we implement our own MVC framework?
- Why did we use this payment broker instead of another ?
As we will see, an ADR derives its strength from transparency and collaboration.
We will also consider a possible usecase outside IT.
There is always a reason to choose
A decision starts with conscious or unconscious reasoning, whether it is a managerial constraint, laziness to explore several avenues, a habit, or a study.
The aim of ADR is to capture this reasoning in the form of a log (Decision Record) with the following properties:
- to be dated
- to be immutable
- to be revisable
- to be traceable
- to be contextualized
- to be explicit
- to be approved by at least one peer
The strength of Decision Records
The architectural decisions you make don’t just impact you. They impact the current team, future developers but also people external to the projects.
- How many technical teams had to be rebuilt from scratch following massive resignations? People leave, decision artefacts remain.
- How many times have you been told: “We have experienced this in the past, I can’t remember why, but it didn’t work”. People stay, knowledge is lost.
- “During our audit we discovered X and Y, can you explain the choices that led to this decision?”
By systematizing the writing of Decision Record you force yourself to start from the space of the problem before entering the space of solutions (explain why before exploring the how).
By systematizing review by at least one peer, you ensure that the choice made is shared and understood by others, that the context is right, that alternatives have been explored. That a future developer will be able to understand this decision.
Notice the glaring similarities with development. It’s not for nothing that most ADRs are actually git repositories, where every decision is a commit, a proposed decision, or a decision review is a merge request.
Interestingly, most of the ADR examples on github have their first decision record: adopt ADR. The technique is used to validate the technique decision.
If the process is correctly followed, the very act of validating the adoption of the technique must go through a stage of contextualization, clarification and approval.
The weaknesses of Decision Records
Like any collaboration technique based on knowledge transfer, it encounters limitations. Let’s take a quick tour of the weaknesses and ways to overcome them.
Cumbersome to write a decision record
It is not for nothing that Thoughtwork talks about “Lightweight Architecture Decision Records”, the goal is to find a decision record format that is easy to write. The form (eg Markdown) can be simplified, but what about the substance?
Complexity of defining a decision record
As with many things, it is about defining the characteristics that define the quality of a decision, allowing its value to be maximized while maintaining a certain pragmatism.
Spend as much time as possible defining the properties you want to achieve. More often than not, solutions will emerge on their own.
If several solutions emerge, do not be afraid to choose a solution and try, there is no such thing as a perfect architecture, if you have defined and documented the properties you want to achieve upstream you have done a great job of architecture, the final choice will then be a measured risk-taking.
Ownership
Here the word is out. Who is responsible for ADR? Everybody ? But if it’s everyone, it’s nobody. The architect? There aren’t always, and he’s not all-knowing anyway.
Here we put our finger on the larger problem of documentation, when it is not documentation by code. At the beginning of the article I wrote that “Architecture Decision Records (ADR) is a technique”, in reality it is a discipline.
This documentation must fit into a definition of done framework, just like a rest API or library documentation.
Beyond Tech
It’s not just developers who have problems with implicit, forgotten or misunderstood decisions. Take any team in your company with some turnovers and you’ll hear the same king od questions:
- Why did you choose Salesforce as your CRM tool? There are better and cheaper solutions!
- Why was the accounting scheme designed in this way?
- Why was the decision made to completely redesign the website’s UI / UX?
- Why did you change the organizational chart of the company in 2016?
- Why did you change your business model in 2017?
This discipline has a greater scope than Tech. Like any technique / discipline it can evolve to be reused and adapted to sectors other than the one that popularized it.
Now I’m going to complete my Life Decision Record explaining why I decided to write an article on ADR.