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
Use of lightweight Architecture Decision Records (ADRs), as described by Michael Nygard, is a technique strongly encouraged in DfE.
You can use ADRs to capture important architectural decisions along with their context and consequences. Recording design decisions in this way:
- enables retrospective review at key points
- benefits future team members to get up-to-speed quickly
- provides a basis for external oversight, where needed
We recommend storing ADRs in source control, to provide a record that remains in sync with the code itself.
There is a wealth of related information on the ADR Github organisation. In DfE, we favour the Markdown Architecture Decision Records (MADR) approach, though appreciate any implementation is better than none.