8 Learnings from using Architecture Decision Records (ADRs) at willhaben
Architecture Decision Records are no new concept. But at the latest when Lightweight Architecture Decision Records made it into the “Adopt” circle in ThoughtWork’s Tech Radar in November 2017, ADRs gained a lot of popularity. At willhaben we started to use ADRs systematically in late 2018. After more than two years of using them in practice, it’s time to summarize what we have learned. Please keep in mind that for the rest of the article, whenever I speak of ADRs, I’m talking about “Lightweight ADRs”.
What ADRs look like at willhaben
Before we present our conclusions, let’s have a look at where we collect our ADRs and what they look like.
ThoughtWorks recommends putting ADRs in source control. We, however, prefer to put them in Confluence. The reason is that we want ADRs to also be accessible to non-technical people in the company, particularly product managers, designers and C-Levels. In addition, we are using a lot of repositories and we wanted to create a central location of ADRs instead of scattering them across multiple source code repositories. Finally, we found that many ADRs affect multiple projects, so it would be inconvenient for us to decide where the right spot would be.
There are a ton of templates available (a great overview and summary is available at https://github.com/joelparkerhenderson/architecture_decision_record). We started with a custom made, simple template that evolved over time. Ultimately, we created a template in Confluence, which is currently structured as follows.
- Title: The title always starts with the date in YYYY-MM-DD format as long with a concise description of what the ADR is about. And finding a good description is not always that easy — As we all know, naming things is one of the two hard things in computer science, so take your time and put some thought into it. Your future you will thank you later. The date format is chosen so alphabetical ordering is also correct date ordering.
- Participants: This is simply a list of people who took part in this discussion. This is useful because it helps to clear up questions such as “but did you ask an app developer?” or “was product management involved in this decision?”. Two days later you might remember. Two months later probably not.
- Status: We have four different states in which an ADR can be:
- Open: It has been recorded as a problem, information might still be missing and discussion has not yet begun.
- In Progress: The discussion is currently going on.
- RFC: All necessary information has been gathered, a proposed decision has been made and now everyone can comment on it (“Request for Comments”).
- Decided: This is the final state — When a decision has been made and recorded and everyone had their fair chance of providing feedback. After that the ADR is closed. It is considered bad practice to modify ADRs later. However, what I do from time to time is to append to ADRs if new information becomes available. - Situation: Here we describe the current situation using only facts. What are we doing? What is the context of this decision? What are the premises and assumptions for this decision to hold? If necessary, also mention what explicitly is not in scope. Be very careful to not talk about problems or solutions in this section, they will be covered separately.
- Problem: What is the problem that arises out of this context which we now need to solve and where an architectural decision is needed? What makes the problem complicated? What are the consequences? This exercise will help you to formulate the actual problem for your users and avoid that the technical solution dictates your problem.
- Options: For each option we briefly describe the proposed solution, its implications, pros & cons. I also always add a “Do nothing” option. This helps to point out the consequences that happen if you keep everything as it is. You might find out that it could be acceptable to do nothing, or it could help you to point out to management why a problem needs immediate attention. I also always explicitly add options that we obviously won’t do. Just adding them as an option to the ADRs doesn’t mean that we are considering doing it. But it helps to document that you have considered all the options and you deliberately choose not to pick it. It also helps to answer “Hey, why didn’t we use xyz” later.
- Decision: Which option has ultimately been chosen? If a final decision has been made, we mark it also as the chosen option in the “options” section. A decision can also be that it’s up to the tribe to pick between different options (i.e., we don’t see negative consequences by picking one or the other or that different tribes pick different solutions).
- Next steps: Until the ADR reached status “Decided, we ensure the ADR records who needs to do what next (e.g. Alice will research whether using FooService provides a Bar endpoint). As it is good practice with every action item, we assign a name and a date to it.
- Timeline: A simple log that holds an entry for each status transition and (significant) amendment to the document. We also announce here when the RFC will end.
- See also: Links to related decisions, confluence and web pages, slack discussion threads, etc..
Learnings
So more than two years and over 80 ADRs later what did we learn from it?
1) ADRs bring structure into discussions
Often enough in my career, I have experienced discussions that looked like this: Some people gather in a room, aimlessly start throwing around a wild mix of opinions, feelings, problems and an hour later leave the room without any decision being made or anything even documented.
By providing a well defined format, ADRs force you to structure the discussion into subsequent stages and bring everyone on the same page. What’s the context we are in? What’s the actual problem we want to solve? What are the options? What are the pros and cons of each option? A format like this helps to organize your thoughts and the discussion and — most importantly — emphasizes decision making.
2) ADRs don’t need to be perfect from the start
ADRs don’t have to be perfect or complete from the start. Just start with the information you have and amend the document as you move on in the discussion.
Before you set up a meeting or start a discussion on an architectural decision, prepare an ADR upfront, which makes a great agenda so everyone knows what the discussion will be about. If you prepare the ADR upfront and involve the right people it might even turn out that you don’t even need a meeting — That way, ADRs can help to cut down on meetings by having discussions about architectural decisions asynchronously.
3) ADRs have both short term and long term benefits
In the two points above I discussed the short term benefits of ADRs. After the ADR is decided, everything is clear (or at least, well, decided) and typically is not looked at for a while.
But after using ADRs for more than two years, we also start to see the long term benefits. Typically after a couple of months to years — at a time where no one remembers the details and heated debates are far gone — questions like this pop up:
Why did we decide on method x? Why didn’t we consider that other technology back then? We have this new problem, didn’t we do a similar thing a while ago — Is there something we can learn from it? How did we do …?
I tried to sum it up in a sketch.
4) Writing ADRs takes time
This is a trivial statement. But often enough the most trivial things are overlooked. When introducing ADRs, keep in mind:
- Not everybody likes to write documentation.
- Not everybody will think it’s a good use of their time.
- Not everybody will think it’s a good use of my time.
- Not everybody is good at writing things up.
- Not everybody likes bureaucracy (which ADRs are, let’s be honest)
At willhaben, I primarily see it as the responsibility of the architect to write up and maintain the collection of ADRs, as it’s also the responsibility of the architect to facilitate discussions and to bring about decisions. I’m not at all opposed to people writing up ADRs themselves, in fact I encourage it. But I also see that engineers in product tribes seldom have time for it rarely happens in reality.
5) ADRs are not a good discussion format
We found that the most interesting and lively debates happen in Slack and in meetings. In the beginning I tried to redirect the discussion to the ADR in Confluence. I ultimately gave up on this idea, and just let the discussion happen in Slack. I then try to summarize and document the outcomes of this discussion in an ADR.
6) ADRs need to be visible and accessible
As soon as an ADR enters the RFC stage, I typically post them along with a short summary and the proposed decision in our main developer Slack channel. That way everyone is informed about important decisions and everyone can voice their opinion on architectural decisions. No one can claim later that they haven’t known/been involved in a particular decision.
ADRs are only useful if people know where they can find them and if they are organized in a way that makes information retrieval possible even after some time has passed.
This is where Confluence doesn’t really shine. Personally, I find the search in confluence notoriously bad. Anyway, using a central place, using tags and concise titles help. You could also consider putting them in a separate space in Confluence.
7) Know when to write an ADR (and when not)
When is it worth writing an ADR and when are meeting notes enough? This one can be tricky to answer and hard to formalize. Our guideline looks like this:
- Is this decision relevant for more than a single issue/epic?
- Is this a topic that could be relevant/interesting for others to know?
- Is this a decision that has a significant impact (i.e., cost) and cannot be reverted easily later?
- Is this decision relevant for more than one tribe?
If any of these questions is answered with “yes”, it’s typically worth writing an ADR. ADRs also don’t have any length requirements. 5 lines of text can be enough, if that’s all there is to know. Remember: Lightweight.
8) ADRs help you to learn from your mistakes
You make decisions, you make mistakes. It’s as simple as that. If something doesn’t turn out the way you anticipated, ADRs are a great way to reflect on what you can learn. Was there anything you could have seen coming? What can you do to avoid the same mistake? This will sharpen your skill set over time and help asking the right questions next time. I make sure to append these learnings as comments in the respective ADRs.
Conclusion
As I mentioned in my blog post “ST*U and listen: Starting as an architect at willhaben”, architecture is always about picking the right tools for your specific circumstances. Some companies have strict compliance and documentation requirements where ADRs just won’t cut it. On the other hand, a small start-up, consisting of only a handful of people that are constantly changing and re-inventing their product should spend their time with rapid development rather than with documenting architecture that changes five times a month.
For the tech organization within willhaben, which consists of multiple independent tribes and that has reached a high level of business maturity, we found ADRs are a good compromise between bureaucracy and facilitating, documenting and communicating important decisions across the organisation.
