The Enterprise Architecture team from Government Digital Service (GDS) is excited to have recently introduced the Architecture Decision Record (ADR) framework. This handy structure is designed to help teams to consistently make and record technology decisions in order to reach the UK government’s goals of better-documented decisions, less duplication and more joined-up delivery.
Documenting decisions is essential across all levels of government departments, particularly for those that need to be brought to the Technical Design Council (TDC). The TDC is made up of empowered Chief Technology Officers from across the public sector as a commitment set out in the blueprint for modern digital government. The TDC is responsible for decisions which affect cross-government architecture and shared platforms, in which ADRs play a major part.
What is the ADR framework?
In the public sector, we make thousands of technology decisions every year. This number will only increase as we work on delivering the ambitious vision set out in the blueprint for modern digital government, which requires us to make better and more consistent decisions. Some are small. Some are huge. But when they’re undocumented, we risk repeating work. When people move on, we can lose context of why decisions were made in certain ways. Most importantly, we miss opportunities to reuse good thinking.
This is where architecture decision records come in. An ADR is a short note that captures a key architectural decision. It’s not a formal sign-off or a long report, but it can be used in formal governance boards and design authorities. ADRs are a way to document:
- the context for the decision
- the options considered
- the decision made
- the reasoning behind it
ADRs are designed to be quick to write, easy to read and useful to others. They also maintain transparency in decision-making.
Our mission is to make ADRs a standard part of the decision-making workflow, which is why we landed on a clear and simple framework to help embed this practice across the public sector.
How we designed the framework
We built the ADR framework using patterns that already work well in government and industry. An easily-replicated accessible format was what teams wanted the most so that even someone who had no prior knowledge of ADRs could understand what was needed.
The point is to make decisions visible, not to add bureaucracy.
This is why the ADR framework consists of two sections. The first section has guidance on when and how to use ADRs and the second one contains a standard template for recording decisions.
The framework is designed to be flexible to reflect the diversity of how our teams work; it can be used in both agile and waterfall programmes, and anything in between.
What we’ve learned so far
We’ve already tested the framework with various teams across the Department of Science, Innovation and Technology (DSIT), as well as other departments, to ensure that it’s fit for purpose. Some great early feedback has indicated that this framework helps to:
- clarify thinking and spot risks early
- onboard new team members more easily
- collaborate better across disciplines
- create a reusable record of decisions
But we also learned that ADRs only work if they’re part of the team’s normal rhythm rather than bolt-ons or box-ticking exercises, so further change may be required to establish the practice of ADRs as standard.
How to get involved in the next steps
We’re encouraging the ADR framework’s adoption across the public sector. While it won’t be mandated for day-to-day team decisions, it will be needed for anything brought to the TDC. We’re inviting more teams to test the framework and tell us what works so that we can adapt and improve it based on your feedback. We’re also looking at how ADRs can support wider reforms, such as reducing legacy risk, improving technical resilience and enabling joined-up services.
If you work in government technology and would like to help us, you can use the ADR framework yourself.
We encourage you to try out the template on your next architecture decision, and then share your ADRs with others in your organisation.
If you have any suggestions or questions, reach out to the Enterprise Architecture team at [email protected].
