If you choose to watch instead of read, here is the video version of this blog post.
Have you ever questioned the decisions made in a software project?
You may be wondering why a certain software solution was preferred over another or how different alternatives were evaluated. On such occasions, you might have wished you could turn back the hands of time to understand the decision-making process.
There is a way to do this without a time machine: Architectural Decision Records (ADRs).
What are Architectural Decision Records (ADRs)?
An ADR is a method used to document the thought process behind decisions made in a software project. It includes every bit of information about the decisions captured, such as the reasons why the decisions were made and the details of the chosen solution.
ADRs serve as a knowledge base that allows team members to understand the reasons and context behind the decisions.
Architectural Decision Records are invaluable resources for knowledge sharing among team members, especially for newcomers. They allow them to dive deeper into understanding the project's evolution.
ADR is a knowledge sharing tool that provides a detailed record of the project's history.
Anatomy of an ADR
Here's what makes up an ADR:
Title
Unique Number
Date
Status (which can be proposed, rejected, accepted, or superseded)
Problem Statement
Considerations
Constraints
Rationale
Consequences (Pros and Cons)
Remember to keep your ADRs concise, readable, and readily accessible to all team members.
ADR Example: Migration from C/C++ to Rust
Let's use an example to get a better understanding of ADRs.
This ADR discusses a team's decision to transition from a C/C++ project to Rust. It explains in the problem statement why they evaluated the possibility of using alternative programming languages.
After listing their considerations and constraints, they discuss Rust's gradual implementation, noting its robust features such as memory safety, security, performance, and a strong type system.
Their implementation strategy details how they plan to slowly replace parts of their codebase with Rust, taking a long-term approach.
Superseding an ADR
In the future, if the team decides to transition from Rust to another language, like Golang, they would need to create a new ADR and set the status of the previous ADR to "superseded".
This indicates that the previous decision has been replaced with a new one. ADRs are immutable: you can't edit them. Only the status can be edited.
ADR Application Beyond Software Projects
ADRs are not restricted to software project decisions. They can also document team structure or operations decisions, such as a company's decision to transition to a four-day workweek.
Benefits of ADRs in Software Projects
ADRs boast several benefits:
They facilitate knowledge sharing among team members.
They foster clear communication among team members.
They provide a central repository of decisions helping new members quickly understand past choices.
They capture important decision-making contexts for future reference.
To effectively manage ADRs, regularly review, update, and keep them up-to-date as the project progresses and new decisions are made. Always remember to keep your decisions up-to-date in the ADRs.
Also, establishing a process for managing ADRs within your team, defining roles and responsibilities, designating someone responsible for reviewing and approving ADRs, and establishing guidelines for how and when ADRs should be updated or retired are good practices.
Implementing ADRs Using Log4brains
Log4brains, an open-source ADR tool, can automate, manage and publish ADRs as a static site. Install it via npm, initialize it, and you're ready to go. The tool automatically generates some example ADRs for you to start with.
To create a new ADR, use the "log4brains adr new" command and then fill out your ADR details. The ADR will be saved in draft status, which you must change once you reach a decision. When writing your ADR, be sure to cover the problem statement, potential solutions, pros and cons, and the final decision.
A Bit of History
The concept of Architectural Decision Records gained popularity in 2011 thanks to Michael Nygard's influential post, "Documenting Architecture Decisions''.
Nygard introduced the ADR and advocated for structured blog posts explaining the decisions made during development, visually similar to an ADR.
Wrapping Up
We've explored the significant role that Architectural Decision Records can play in software project documentation.
ADRs enhance knowledge sharing, promote consistency within teams, and help maintain an invaluable project history. Implementing ADRs can significantly enhance collaboration, drive accountability for decisions, and ensure long-term project success.
If you found this post helpful, consider sharing it with your colleagues. As developers, cultivating a continuous learning culture is key to smoothly navigating the ever-evolving tech industry.
May the force be with you!
