On agile projects, architectural decisions will not all be made at once at the beginning, but also sometimes as we iterate on the product. So, we need a way of documenting architecture decisions made along the way.
Architecture Decision Records
An architecture decision record is a format to capture the context of a problem, and the technical decision taken to solve the problem. It also captures the details of assumptions, consequences and mitigations. And mainly they serve as a historical record of why the decision was made, and help new team members to get that context easily.
An ADR could span many levels of the architecture, something that only affects a single service, or something that affects few services and calls out a pattern to migrate to, or something that has wider business impact. They can be stored in the source code repository, and committed along with the relevant code for the change.
ADRs can also be used as a communication and alignment tool for architectural decisions. They can facilitate an RFC-style process, as long as relevant stakeholders have access to the document and can make comments. If the source code repository is only accessible by developers, for instance, it may be better to host it on a team document platform instead.
Remember to:
Track the status of the decisions over the period of the project, either update or override a decision if needed.
Tag all necessary stakeholders on the document, Record with classification of owner/reviewer/participant to track right people have paid attention to the decision.
Reuse architecture diagrams owned by the team, and not create separate diagrams that lives only in these records.
Reference these high level decisions in other ADRs which get documented in the code.
Link to other artefacts, rather than copying them over or turning it into a long page of design notes.
Focus on the consequence of an architecture decision, and aligned it with the long term view and the final outcome of the project.
ADRs are crucial for collaborative decision-making, highlighting the consequences of a decision and guiding a wider team.
