We can’t stress the importance of documentation in software architecture. The decisions that you make today will impact the project now and may lose context and understanding in the future. Documentation can help others understand what problem was being addressed, what options were considered, and why a decision was made.
As I mentioned in the Practicing Architecture Katas post, Nate Schutta mentioned architecture decision records (ADRs) during his “Thinking Architecturally” workshop at CodeMash. When I attended Explore DDD earlier this month, I heard about ADRs in many sessions. In one, Indu Alagarsamy suggested that decision records could apply to architectural decisions, product design decisions, or other decisions involved in a business. I’m a huge fan of documentation, so if I can document it, I will.
What to Include
What are some of the things to include in a decision record? Some of the things you might want to capture include:
- Title
- Status: such as Draft, Proposed, Accepted, Rejected, Deprecated, or Superseded
- Problem
- Options
- Decision
- Consequences / Outcomes
Depending on the company environment and the person documenting the decisions, there may be other things included, such as:
- People and/or departments involved in making the decision
- Cost matrixes and comparisons for multiple options
- Analysis artifacts
- References to related decision records
- References to resources involved in any research to assist in decision making
When to Write Decision Records
In the CodeMash workshop, one of the attendees asked about when ADRs should be written. If you can capture everything in context, that’s the best.
Can we write decision records retroactively?
Yes, and by doing so, you capture as much as you know about the decision that was made, making note that the decision record was created retroactively and that certain contexts may not be caught. If you’re capturing a decision record retroactively, be explicit about what details or contexts are missing.
Where to Store Decision Records
Another question that came up during the workshop is where to store ADRs. Typically, you want them to live in a spot where they can be seen by everyone they impact. This could be something like a document within a document controlled environment, a folder on an intranet, or some other document storage system. It also helps to link related ADRs by referencing IDs or using hyperlinks where possible.
With the developer mindset, there’s a question of Can my decision records live in the same repo as my code? I’m going to caution you on this - will those impacted by these decisions be people outside of the source control? Would the documents living in a repo make it complicated for stakeholders to access it? Do you have non-technical stakeholders who wouldn’t need repo access otherwise? While I understand why you would want to include decision records with your code, I would caution against it unless your decisions that are in your repo are purely related to the code stored in the repo and impact only those who need to access the repo.
Sample ADR
One of the things we do at NimblePros is have lunch-n-learns around architectural topics. In a recent lunch-n-learn, we were proposed the following situation:
We have a shopping website. How can we get info on the book price from within the shipping module?
As we were talking about possible solutions, I thought - I should create a sample ADR! So I did, and you can get it here: Sample decision record.
Conclusion
By documenting what decisions were made, why they were made, and the context surrounding them, teams can navigate complex architectural landscapes with confidence and coherence. Storing ADRs in a centralized storage location accessible to all stakeholders ensures visibility and fosters collaboration, while establishing a culture of continuous improvement and learning. Whether it’s outlining architectural principles, documenting trade-offs, or capturing rationale behind design choices, ADRs serve as a compass guiding teams towards architectural excellence.
Embracing the practice of writing and maintaining ADRs not only enhances the quality of software systems but also cultivates a shared understanding and alignment within the team. As the software industry continues to evolve, the adoption of ADRs stands as a testament to the commitment towards building robust, scalable, and maintainable systems that meet both present and future needs. The decisions that you make today will impact the project now and may lose context and understanding in the future. Capture the current context so that future you understands why and how this decision was made. Document your decisions in decision records!
Additional Resources
- Getting Started with Architecture Decision Records (Ardalis)
- Joel Parker Henderson’s GitHub repo on ADRs - great list of examples
- Architecture decision record - Microsoft Azure Well-Architected Framework
- Architectural Decision Records - AWS Prescriptive Guidance
- Architecture decision records overview - Google Cloud