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.
In DfE, architects are trusted to choose the most appropriate way of documenting their design thinking, decisions and rationale, in a way that best fits with their delivery.
It’s important that design is done in the open and architects share their thinking across the community. The architecture profession provides various tools, techniques and guides to help architects do that.
Architecture Decision Records
Architects are responsible for architecture and design decisions in their portfolio, service or domain. They should be confident representing these decisions in their communities and at DfE governance or assurance forums.
Important architecture and design decisions should be recorded using lightweight Architecture Decision Records (ADRs). ADRs capture the decision, its context and its consequences, providing a record that can be reviewed and understood by others.
Recording design decisions in this way:
- enables retrospective review at key points
- helps future team members get up to speed quickly
- provides a basis for external oversight, where needed
- makes it easier for architects to explain and represent decisions in governance and assurance forums
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.
The use of lightweight ADRs, as decribed by Michael Nygard, is strongly encouraged in DfE. In DfE, we favour the Markdown Architecture Decision Records (MADR) approach, though appreciate any implementation is better than none.
You can find more information about ADRs through the ADR Github organisation.