The buzz around AI often only revolves around how fast and cheap it is to genereate code. And it is true: Developing small tools has gotten waaaayyyyy cheaper.
Software systems on the other hand are a lot more than code:
- They are business requirements
- They are tradeoffs
- They are design decisions
- They are built on incomplete knowledge
- They are limited by technology
- They are documentation
While AI may help in many items of the list, too, there is a lot of human interaction and need for human involvement. Humans need documents and other things to reason about.
Imho one important aspect are the decisions we made in the context, at the time. This is often overlooked and development teams and/or customers ask themselves later, why things were done the way they are now. Sometimes discussions go round in circles and discoveries of the past are rediscovered again and again.
ADRs to the rescue!
This is where Architectural Decision Records (ADRs) can help tremedously! They do not only describe the status quo of a system or feature but provide additional insight. Typical ADRs document the decisions taken in a structured and referencable way. Besides the decision itself they contain metadata like
- An identifier
- The people involved
- The context
- Several alternatives that were discussed
- Pros, cons and consequences of each option
- The reason for the decision
The catalog of ADRs usually grows gradually during the life of a software system. Like the system itself and its environment the ADR catalog is not static but dynamically changing:
ADRs can become invalid, they can be superseded by newer ones and may have other statuses like proposed, accepted and rejected. The identifier allows them to be referenced in other documentation, issues and code comments.
Over the years they provide a description of the journey the people involved and the software system took together. This journey may not have been a short and straight one but often had many twists and turns.
All that can be seen an tracked in the ADR catalog. The current team and customer can take a look at the journey and identify place to revisit or paths to avoid because it is documented in an appropriate way.
Do we need even more documentation than we have already?
Projects usually have a decent amount of documentation, so you may ask: Do we need even more? And how much effort should go into something like ADRs?
I think, ADRs offer different and very valuable information while being designed to be very lightweight. Most people use Markdown templates for there ADRs so you have a standard format making it fast to create and being skimmed over. MADR seems very popular and I also like aspects of tekiegirl/Archangels templates.
Defining your own template that fits your needs best based on those suggestions should not be that big of a deal. Neither is starting to use ADRs in your running or future projects:
Just document every decision that meets one or more of the following criteria
- impacts the implementation
- hard or expensive to reverse/change
- topic comes up repeatedly in meetings
- new members ask repeatedly about it
- affects multile teams, services or systems
- difficult to explain without the context
- overrides or adopts decision by another team
Conclusion
ADRs are a lightweight documentation tool offering a unique and very useful perspective an a project/software system. You can start using them right away to get benefit and can reference them in several other places like issues, documentation, commits and code. Keeping them as close to the code as possible (e.g. in the same code repository) makes them easier to find.
There are and surely will be more and more tools that can use the information in your ADRs to help you reason about your system, its history and its future.
Schneide Blog 