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 described by Michael Nygard's blog post 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.
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.