Architecture Decision Records (ADR)
Overview
An Architecture Decision Record (ADR) is a document that captures a decision, including the context of how the decision was made and the consequences of adopting the decision.
ADRs are usually included with development documentation inside of a project repository. For now we can add them to our engineering space.
What are the benefits?
- Onboarding - Future team members can read a history of decisions, why they were made, and their impact. This is much like a CHANGELOG but for architecture instead of code.
- Ownership Handover - When a team or organisation changes, we sometimes have to move ownership of systems from one team to another or from one person to another. By having ADRs we don’t lose context or knowledge.
- Alignment - It will help improve alignment amongst project teams. This includes teams making decisions together, working more closely together as well as cross functional teams making code reusable and deduplicating efforts.
When should you contribute
- Backfilling decisions and solutions - When a decision has been made that breaks standards and there is no documentation on why that decision exists. We can sometimes identify an undocumented decision is during Peer Review with the introduction of a competing code pattern but this is generally too late down the development cycle.
- Proposing large changes to a system - Over the lifecycle of a system, you will have to make decisions that have a large impact on how it is designed, maintained, extended, and more. Along with the use of system design reviews, architecture reviews and functional requirements we should also document large changes.