Architectural Decision Records

Create ADRs when making significant and impactful decisions.  Retain those decisions in a way that ephemeral media like email, video calls, and IM channels do not.

Architectural Decision Records (ADRs) capture architecturally significant decisions or design choices and the context and consequences for the decisions. ADRs exist to help people in the future understand why an approach was selected over others.  This includes future you, new team members, and future teams that take over responsibility for systems or processes that were impacted by the ADR. 

The typical ADR consists of:
Problem StatementThe problem statement that drove the need for an ADR
Current Status Draft, approved, declined, etc.  Some ADRs will be abandon for other approaches or changes in direction.
Alternatives The viable alternatives that were considered and their pros and cons.
Decision The chosen solution including enough information to give direction to those that did not participate in the discussion.
Impact and implications Side effects, technical, staff, training, customer
Related decisions, other ADRs Cascading decisions or impacts on previous work.
Context DiagramsMost people are visual thinkers. Include context diagrams where they can help someone in the future.

In some environments, ADRs also capture some RACI matrix actors:
Role Description
Responsible The person or persons who raised the issue or created the ADR
Accountable The person who had to approve the decision, often the lead
Consulted Team members and partner team members
Informed People or teams that were impacted or were notified.

ADRs can be used for technical and non-technical decisions as shown in some of the links below. 

They are not

An ADR is not intended to defend a decision or act as a shield against criticism. It exists to provide information for the initial implementation and to provide context for additional work in the future.

Who Benefits? 

ADRs offer significant benefits over ephemeral channels like conference calls, email, and team channels. The decision lives beyond the shelf life of the media or the tenure of individuals on the team.

Future You: They aid you in future discussions when making decisions that sit on top of the ADR.  You can go back and remember any subtleties or risk areas in that space.

Current and future peers and team members: ADRs make the decision process and results available to other team members and to new team members that join the group down the road.  ADRs can reduce the amount of 1:1 knowledge transfer required when onboarding new teams or partners.

Ownership Changes: Projects and programs often change ownership during corporate reshuffling or reorganization.  ADRs can provide a foundation for how something is structured and why. It also helps the new owners avoid the "why did they do it this way" trap.

How should they be stored?

ADRs are simple.   The storage format should be simple, long lastable, and easily indexed by search engines. The documents should be stored where they can be found and where their lifecycle matches the lifecycle of anything built from the ADR.  

Purpose Location Format
Software design, SDLC, code organization In the source tree.  Git has standardized locatonsUniversally editable format like Markdown. See sample Markdown templates below.
Departmental or enterprise architecture level ADRsInternal Wikis wiki markup
Program or enterprise-level ADRs Sharepoint-style sites. native format

ADR Templates and other articles


Created 2021 06 29


Popular posts from this blog

Understanding your WSL2 RAM and swap - Changing the default 50%-25%

Installing the RNDIS driver on Windows 11 to use USB Raspberry Pi as network attached

DNS for Azure Point to Site (P2S) VPN - getting the internal IPs