Why?

I have experienced a lot of conversations with engineers that bemoan that do have the historical context of why certain decisions were made, what were the constraints and what were they trying to optimise.

Documenting our decisions in a wiki using an architectural decision template should help make good decisions now and also allow people who follow after us to understand the What? Why? How? of the decisions taken.

What is a Architectural Decision Record (ADR)?

A quote taken from https://adr.github.io/

An Architectural Decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. An Architectural Decision Record (ADR) captures a single AD and its rationale; Put it simply, ADR can help you understand the reasons for a chosen architectural decision, along with its trade-offs and consequences. The collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM), but ADR usage can be extended to design and other decisions (“any decision record”).

https://adr.github.io/ is a great reference and should be used as a place to expand your understanding of Architectural Decisions.

Lifecycle of an ADR

Creation

Fill out the chosen ADR template, making sure you capture the problem and rationale behind the decision. This should be submitted for review.

Review

Tech Leadership should meet to review all architecture decision records submitted for review. If the ADR is rejected, it should be updated with the reviewers decision why, this helps us in case in the future a similar proposal is submitted and we need to understand why it was not approved the first time.

Retrospective

After implementation of the ADR, a retrospective should be held to create a feedback loop and make sure we are learning from our decisions.