Tools: Power Of The Paper Trail: Architecture Decision Records (adrs)
The ultimate output of knowledge work,in this case software architecture and engineering, is decision making. Regardless of what form it takes, recording the thought process of key decisions is an important part of maintaining clarity before, during and after decision are agreed upon, to help prevent hind-sight bias and to allow your future self and others, understand the environment in which the decisions were made.
In this post I will be sharing what I have been learning about Architecture Decision Records their applications in software and data projects.
Architecture Decision Records are essentially a paper trail for significant architectural decisions that you make in the lifecyle of a project. I will mostly refer to them as ADRs from now on.
In my years as an software engineer and data engineer, I have scarcely, if at all come across this ADRs. Documentation has taken many forms in the projects I have been apart of; abandoned Notion pages, diagrams and sparsely detailed text files about what was going to be implemented or has already been implemented, or no documentation at all. When decison change, ADRs help track this by introducing states to these documents i.e Propose, Accepted, Rejected, Superseded
Architectural decisions are some of the most costly in any organization. They have impacts on how easy it will be to add features or how resilient and flexible the system will be to changing requirements of the business. Interrogating and justifying these decisions with a decent amount of rigour, within the required time-frame becomes that much more important. Not to mention the framework can be adopting to many other fields and types of decision processes.
Not every decision warrants a paper trail; the administrative overhead would be a nightmare. Michael Nygard describes "architecturally significant" decisions as those affecting:
Ask yourself: Is this decision reversible, and what is the cost of reversing it?
Olaf Zimmermann goes into great detail on this in his blog post about what criteria to use. regarding decision criteria
I'll be the first to hold up a cross to administrative overhead and because gaining initial velocity on the habit of documentation is hard enough, lightweight ADRs make for the best format to help reap the benefits of documenting your decision without dramatically affecting your workflow.There are even tools that help you manage ADRs, which you can find in this gihub repo to help grease the wheels.
In my projects, I si
Source: Dev.to
