Architecture Decision Records Insight: Deciding What Belongs
A common problem I have encountered is uncertainty regarding the categorization of Architecture Decision Records (ADRs). While I appreciate the concept of ADRs, I often find others pondering whether a specific issue qualifies as a technical decision or a mere detail. This article centers around precisely this topic. How can we improve our understanding of what constitutes an ADR and what does not? Continue on as I delve into this matter to shed light on the distinction.
Understanding Architecture Decision Records
Software architecture revolves around trade-offs and constraints. Have you ever been on a project and heard questions like “Why are we doing it that way?” or “Why didn’t we choose this alternative?” Making technical decisions about architecture is important, but even more crucial is documenting those decisions to help others understand the reasoning behind them. ADR serve the purpose of recording the history of decisions made during a project, not the state of things. ADRs provide context, consequences, and reasons why different options were considered and rejected. I have often found that ADR create a more improved collaboration, and better understanding of decisions as we documented the decision. It gave us an opportunity to not just talk about the what but also the why.
Exploring Solution Documents
On the flip side of ADRs, there are solution documents that outline the high-level design of an upcoming solution. Solution documents encompass technical details, requirements, and implementation plans. This is where people can learn how to implement software effectively.
Problem: ADR vs Solution Document Content
However, a problem arises: many people are uncertain about when to create an ADR. ADRs contain technical decisions, while solution documents contain technical details. Let’s delve into more details to help clarify when an ADR should be created.
When to create an ADR
Here are some high level times when you would create an ADR and some examples to help illustrate.
When there are significant technical decisions or choices that could impact the system’s architecture, design principles, or other critical aspects.
- Decision between two product choices
- Decision between the type pattern to use
- Decision about technology stack choices
When there’s a need to explain the rationale behind a chosen solution.
- Product Options and Configurations
- General Guidance and Best Practices
When discussing consequences, trade-offs, or potential risks of decisions.
- Deployment decisions
Having to make urgent or important decisions
- When needing to make technical debt conversations
The goal here is to maintain clear and organized records that effectively communicate the right information to stakeholders and teams. Just as in coding, where you write code for the benefit of future readers, the same principle and mindset should apply to ADRs.
Best Practices for Documenting Architecture Information:
- Use titles that focus on the decision rather than the solution or technology itself. Think about the high level problem.
- Remember that ADRs can become superseded and should be periodically reviewed and updated to accommodate new decisions (a new ADR record)
- Use of GitHub to document and publish ADR as well as have an asynchronous conversation using GitHub tools.
- Don’t fill out an ADR without first discussing it. Start discussions with only filling out the context section.
Conclusion
I would love to hear about the ADR examples you have created. Your contributions would greatly assist others in understanding the various types of ADRs that can be generated.
