Architecture: work in progress
Architecture documentation
- Last reviewed
- 18 June 2026
Learn how architects in DfE document design decisions, share architecture thinking and use decision records.
Record important architecture and design decisions so that others can understand what was decided, why it was decided and what the consequences are.
DfE architects can choose a documentation approach that fits their delivery, but should use lightweight architecture decision records for important decisions. Architects should share these records and their wider design thinking with the architecture community.
Use Architecture Decision Records
Use lightweight architecture decision records (ADRs) to document important decisions. An ADR records the:
- context for the decision
- decision that was made
- consequences of the decision
Keeping this record:
- helps others review decisions later
- helps new team members understand previous decisions
- supports external oversight, where needed
- helps architects explain decisions in governance and assurance forums
DfE recommends the lightweight approach decribed by Michael Nygard's blog about documenting architecture decisions.
Store decision records with technical documentation
Store ADRs in source control with your design and technical documentation, preferably in GitHub. This keeps decisions close to the code and makes changes easier to track.
We recommend storing ADRs in source control alongside other design and technical documentation, ideally in GitHub. This keeps the record close to the code and other technical documentation and makes it easier to track changes over time.
In DfE, we favour the Markdown Architecture Decision Records (MADR) approach. However, using another ADR format is better than not recording decisions.
You can find more information about ADRs through the ADR organisation on GitHub.