4 April, 2024
by Mark Teisman
I only recently became familiar with the concept of Architectural Decision Records (ADRs). I love the idea, and find it a breath of fresh air after compared to long-winded Request For Comments (RFCs) that are written for changes big and small.
An ADR is a document that captures an important architectural decision made while developing a software project along with its context and consequences. It is a way to track the architectural history and reasoning behind decisions made during the project. The lack of an understanding for past architectural decisions was actually the main motivation for our organisation to adopt the "RFC process". To me it feels like ADRs are well equipped to institutionalise an understanding of such historic decisions.
I plan to use ADR Tools to document decisions in a Flink project I'm working on. We'll store the ADRs alongside our code in the doc/architecture/decisions directory. I intend for the ADRs to be succinct. We'll have reviews of ADRs in merge requests, but may try the ADR review meeting if the merge request review turns out to be too light of a process. I'm excited to give this a shot!