000 - Record architecture decisions
Date: 2022-03-14
Status
✅ Accepted
Context
As we build out our systems and services run by NVVS DevOps, we will collectively make decisions around the architecture, processes, and tooling.
When making these decisions, we should record them, both to help us understand and remember why we made them, and to also act as a reference for onboarding new team members and to help teams working in related areas understand why we made them.
Finally, as outlined in the Government Design Principles, these should be publicly accessible as making things open makes things better.
Decision
We will use Architecture Decision Records, as described by Michael Nygard in the article “Documenting architecture decisions”.
Consequences
Michael Nygard’s article, linked above, talks about the following consequences:
- One ADR describes one significant decision for a specific service. It should be something that has an effect on how the rest of the service will run.
- The consequences of one ADR are very likely to become the context for subsequent ADRs. This is also similar to Alexander’s idea of a pattern language: the large-scale responses create spaces for the smaller scale to fit into.
- Developers and service stakeholders can see the ADRs, even as the team composition changes over time.
- The motivation behind previous decisions is visible for everyone, present and future. Nobody is left scratching their heads to understand, “What were they thinking?” and the time to change old decisions will be clear from changes in the service’s context.