October 26, 2018

Documenting Architecture Decisions

  —Lightweight Approach to Documenting Architecture

In Visual Architecting Keynote, Ruth Malan shares a keynote she presented as part of the 2017 Linda M. Northrop Software Architecture Award. I find the “trace” for Ruth’s talk very helpful to understand the context of her slides. The slides are worth the time to review. Just chasing down the references turned up a rich set of insights for me.

Ruth does a nice job of conveying the notion of architecture. She quotes Grady Booch “Architecture represents the significant design decisions that shape a system.” and “Significance is measured by the cost of change.”. Marcel Weiher points out this echos the criteria used to decompose systems into modules.

The modularizations are intended to describe the design decisions which must be made before the work on independent modules can begin. … the intention is to describe all “system level” decisions (i.e., decisions which affect more than one module).

Significant cost of change implies decisions affecting multiple modules.

The Architecture Design Record (ADR) to the rescue? The ADR is a decision template proposed by Michael Nygard to capture design decisions. The template is based upon the Alexandrian Form used in pattern literatue. Michael Nygard’s article includes hints on a workflow for the decision template. Comments in the article link to this SATURN 2017 Talk which provides insight on their use and examples.

During the SATURN Talk, the presenter mentions that when ADR was first employed, is seemed like everything was in an ADR. A combination of goverence and workflow helped make the ADR effective. Workflow changes included using ADRs during reviews and making sure that they were top-of-mind during design. It also includes a little history on the notion of ADR.