Menu
We are putting a process in place where all architecture changes must be documented.
Are there any standard templates for documenting alternatives and decisions?
564
When should I write an Architecture Decision Record (ADR)? If you have made a significant architectural decision that impacts how engineers write software then write a ADR. ADR's are used to document decisions made related to system design and engineering best practices.
An architectural decision record (ADR) is a document that describes a choice the team makes about a significant aspect of the software architecture they're planning to build. Each ADR describes the architectural decision, its context, and its consequences.
Store your ADRs close to your application code, ideally in the same version control system. As you make changes to your ADR, you can review previous versions from source control as needed. You could also use another medium like a shared Google Doc or an internal wiki.
Depends on how detailed / formal you want to be. In terms of a Decisions Register we'd normally use one doc per area / decision, although recently we've been experimenting with OneNote.
At the very least you want to record (for each option):
A succinct bullet-point list of pros & cons (etc) is usually sufficient - it doesn't need to be a big doc.
For a more in-depth / formal / complex scenario you'd want to go further, this is the format we were using in such cases:
Summary
Evaluation Criteria
(This is important as it sets out the criteria you used to score the available options, including weightings etc).
Summary of Recommendations
[Option 1…N]
Recommendation
94
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
