Do you use Architectural Decision Records (ADRs)?Last updated by Yazhi Chen [SSW] about 1 month ago.See history
Architectural Decision Records (ADRs) are lightweight documents use to record important decisions in your project. They do not necessarily have to be related to architecture, but could be any important decision made by the team.
- Lack of transparency and communication
- Loss of intellectual property
- Loss of historical context
- Risk of repeating mistakes
- Difficulty in auditing and governance
- Providing documentation and historical context
- Collaboration and communication
- Informed Decision making
- Decision re-evaluation
- Avoiding blind acceptance or reversal
The act of documenting an important decision, forces developers to think more objectively about their decision. If the decision is likely to cause contention it may be quicker to document it via an ADR and get feedback, than it would be to implement the change and let the reviewer try to infer your reasoning.
ADRs can also help with knowledge sharing across teams, as other Solution Architects will have access to a succinct explanation of the problem and the decided solution.
Another benefit is that future developers joining the project now have access to the historical context as to why certain decisions were made.
They should be stored wherever the technical documentation for your project lives. Storing them in Git along with your code works well, but alternatively wherever your technical documentation lives (i.e. a wiki).
There are several tools available to help create and managed ADRs, but one of the best ones is Log4Brains. Log4Brains can help to create and view ADRs.
This can be installed by running:
npm install -g log4brains
You can then initialize your git repo by running:
Which will guide you through a simple setup process.
To create a new ADR, run:
log4brains adr new
Lastly, to preview your ADRs, run:
You can see more examples of ADRs with log4brains in action on our SSW.CleanArchitecture template.