- Status: accepted
- Dates: proposed - 2020-10-27
- Authors: Damir Murat (
damir.murat.git at gmail.com) - Reviewers: None
We want a light way means of tracking and describing architecturally significant decisions made during this project. Selected methodology should include appropriate templates and possibly other tools to help with documentation consistency.
- System (
klokwrk-project)
We will use the architecture decision log expressed as a time-ordered collection of Architecture Decision Records (ADRs). Architecture decision log is nothing more than a simple index of all available ADRs.
We will use custom ADR template. It includes parts of following "standard" ADR templates:
- ADRs provide a way for communicating, collaborating, and documenting architecturally significant decisions.
- Writing ADRs requires conscious thinking and light elaboration of significant decisions, which leads to better decisions.
- The provided architecture decision log helps with maintaining and onboarding.
- Writing ADRs takes time. As we progress and gain experience, time requirements should shrink.
- Using custom template might cause problems with available ADR tools. However, we don't consider tooling support as important requirement.
- Writing ADRs requires some time to get used to, and have some (minimal) learning curve.
- Not documenting critical decisions.
- Using more elaborated process, for example, using RFC documents and process as proposed by Patrik Kua in CROZ internal workshop.
- We do not want any overhead at this point, so more light way approach is preferable.
- Michael Nygard's article introducing ADRs.
- SATURN 2017 Talk: Architecture Decision Records in Action - Michael Keeling
- Communicating and documenting architectural decisions - David Ayers
- Architectural Decision Records - adr.github.io
- The Evolution of Comcast’s Architecture Guild
- Using Architecture Decision Records – Jonathan Wolski
- SATURN 2019 Talk: Creating, Reviewing, and Succeeding with Architectural Decision Records - Ken Power
- Share the Load: Distribute Design Authority with Architecture Decision Records
- List of system quality attributes
- Decision Log