Architecture documentation

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, for capturing 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 getting up-to-speed quickly, as well as providing 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.