ADR-012: Adopt an ADR Template
| authors | last revised |
|---|---|
| Shon Feder | 2021-12-05 |
Table of Contents
- Summary (Overview)
- Context (Problem)
- Options (Alternatives)
- Solution (Decision)
- Consequences (Retrospection)
Summary
In the context of our development of Apalache facing the need to communicate and record our significant decisions we decided for adopting an ADR template adapted from the "Alexandrian Form" to achieve concise and consistent records of our architectural decisions accepting the regimentation and loss of unexpected possibility that comes with adopting a template.
Context
The development of Apalache is picking up momentum. We have more contributors joining us immanently, and hope to welcome and support external OSS contributors soon. As the number of contributors grows, so does the importance of establishing supports to encourage communication between individuals and accross time.
Maintaining records of architectural decisions (aka "ADR"s) is advised by informal.systems company policy, but the details of how such records should be written, kept, or used, have not been settled. I hypothesize that we have much to gain by experimenting with a consistent, well reasoned format for our ADRs. I think it will help us be mindful of their purpose, make them more useful as diagnostic and prognostic tools, and help reduce the amount of time needed for drafting and approval.
Options
While considering approaches to ADRs, I consulted the following resources, and many of the children links to found therein, :
- https://adr.github.io/
- https://github.com/joelparkerhenderson/architecture-decision-record
- https://en.wikipedia.org/wiki/Architectural_decision
I was surprised by the amount of literature surrounding this topic, and wanted to select something that would help focus and clarify our ADRs, while avoiding any undue burden that might come from associated management or development practices.
Each approach to ADRs can inspire a family of templates. I found most of them to be too involved or intimidating, and I opted for the most light weight approach I could find, while making some changes to clarify the language and content to support our context and existing styles of communication.
Solution
I propose adopting this simple articulation of ADRs and their purpose as our guide:
An architecture decision record (ADR) is a document that captures an important architecture decision made along with its context and consequences.
(see https://github.com/joelparkerhenderson/architecture-decision-record#what-is-an-architecture-decision-record)
Following the Teamwork advice offered in that same document, I propose adopting an ADR template that puts all emphasis on the key purposes of the communication, leaving it up to each author to fill in the template with as much or as little detail as they think necessary to support the particular decision in question.
To this end, I propose this template, which is adapted from the Alexandrian pattern. This template is itself adapted from the so-called "Alexandrian form". Martin Fowler has a succinct summary of its qualities in its native context of "design patterns".