How Decision Records Fuel Sustainable Growth
4 min read
Architectural Decision Records (ADRs) are about persisting decisions for others in the future.
Every day on the job, you make decisions. Those decisions have a context and specific drivers. Often, you consider several options for solving a problem. Each one has its pros and cons. In the end, you decide, which has consequences. Good and bad ones (hopefully, the good ones prevail 😉).
Your choices serve you well as time passes, but the world changes.
At some point, either you or a colleague might revisit the decision.
The outcome of the decision no longer fits, or there is room for improvement.
Without historical knowledge, it will be challenging to determine the new requirements.
New ones might contradict some prior ones.
But we don't know because we no longer have those previous requirements.
Reality shows that they can only be partially restored at best.
This makes a new decision difficult.
Returning to the first decision-making and inspecting these initial requirements would be great.
Decision records help you do that.
Typical examples for decision records:
- Stack decisions: Choosing a library that helps us with the feature.
- Architecture decisions: We have various architectural ideas and must pick one.
- Solution constructs: Why structure our code a certain way?
Make writing down easy and routine #
Short templates provide a skeleton #
A decision log can be as simple as a summary of
- decision drivers,
- considered options,
- positive and negative consequences,
- and the final decision.
The following metadata provides further insights:
- status (proposed, accepted, deprecated, ...),
- deciders (involved people),
- story link you are working on
- the date
To avoid starting at a blank page, several skeletons help you to get the job done quickly. You can find them here: ADR templates
Daily routines enforce the written log #
Remember to write decisions down. Make it part of your routine. This is hard but crucial for success. In the beginning, you might miss some occasions where it could be helpful. But don't give up hope. You can still write it down when the first person approaches you for an explanation.
Written Records enable better collaboration #
Here's how you can turn conversations for the better with it: Let's consider some conversations you may have in your day-to-day activities between:
- Engineer and Architect
- Two engineers, where one is a new hire
- Cross-team communication
When rethinking solutions #
Exhausting Conversation
Bob: "Well, we have the problem that our view count service receives a lot of traffic from our feed service. Shouldn't we introduce circuit breakers?" The most appropriate short form I could come up with to describe the problem.
Pete: "Huh? These are part of our policy. Why aren't they built in there?! Please do it ASAP." damn, what the hell are these guys doing?!
Bob: "OK, I will bring it to the team." why are you so mean? This setup has its history.
Helpful Conversation
Bob: "Well, our view count has recently received a lot of traffic from our feed service. Let's rethink our decision (link) about skipping circuit breakers and introduce them now." thank god we have decision records, and I don't sound like an idiot who has no idea about our internal policies.
Pete: "Oh, I see, there's quite a history. Revisiting this decision with the emerged load patterns is a good idea."
Bob: "Great, I'll write a proposal and send it for review." Nice, that was helpful.
When understanding solutions #
Exhausting Conversation
Bob: "Since my start last week, I recognised a service call connection between service x and y. What's it all about? Why is it the way it is?" Wow, that looks weird.
Peter: "Sure, I can explain the setup, and we can discuss it." Hmm, I already explained it to some other folks recently, and now, I have one more. I would rather do something else.
Bob: "OK, I'll send you a meeting invitation." and one meeting more. puh.
Helpful Conversation
Bob: "Since my start last week, I recognised a service call connection between service x and y. What's it all about? Why is it the way it is?" Wow, that looks weird.
Peter: "You can read about it here (link). If you have questions, bring them to our next team discussion." thank god we have documentation, and I can focus on my current task.
Bob: "Got it, thanks." great, I can read it while travelling this evening.
Log decisions across the organisation #
In practice, we work inside organisations with agile solution trains. Each one consists of many delivery teams. Architecture and product roles help coordinate and prioritise. Each organisational level has its own focus.
Solution Train Level
High-level decisions that impact several teams happen here. People from tech, product and management work together. Choose a solution where everyone can collaborate. This ensures everyone involved has access to the relevant information and contributes insights. Getting non-technical people to learn Git may not be the best fit.
Team Level
Each team develops and maintains a couple of services. Cross-service or product decisions happen here. Again, tech, product and management collaborate. So, you want to use the same tooling as on the solution train level. You can even span a graph via cross-referencing decisions. It highlights how decisions on each layer work hand in hand.
Technical Level
Technical decisions should be as close to the code as possible. Please don't document something you can look up by reading the code. Remember: Keep a single source of truth. Generate all the other views you need from this single source.
Conclusion #
You make decisions every day. Intentional or unintentional. Writing them down at every organisational level is essential. A decision log can be as simple as a summary of the drivers, options, consequences, and the final decision. Some metadata like the status, deciders, and date provide further insights.
Keeping a written log of your decisions...
- ...helps everyone in the team to remember why a solution is as it is
- because less time is spent researching why a solution is weird
- ...helps onboarding new team members with async knowledge exchange
- because everyone can read it themselves at their own pace and time
- ...less risk of losing essential team knowledge
- because no knowledge is bound to specific team members
Done right, it simplifies collaboration and reduces friction. A key pillar for ongoing progress and growth within the organisation.
Now I turn back to my docs and create my second ADR, having decided in the first to write ADRs in the future.