Skip to content

ADRs

What is an ADR

ADR stands for Architecture Decision Record.

From the ADR GitHub organization's home page:

An Architectural Decision (AD) is a software 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 a software system’s architecture and quality. An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; 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”).

Why ADRs

An ADR serves two purposes:

As a communication tool, it provides all the relevant information required to make an informed architecture decision.

It helps decision makers to make an informed architecture decision without having to go through the whole analysis themselves.

As a documentation tool, it provides a record of an architecture decision and of the information that was used to make that decision.

Whether after 3 months or 3 years, we have access to the underlying reasons for why a particular architecture decision was made.

When should I write an ADR

As often as possible

ADRs should be easy to write. Whenever you are faced with an architecture decision, you should be able to:

  • express the issue succinctly
  • identify relevant solutions
  • evaluate each solution's benefits (pros) and drawbacks (cons)
  • come up with a recommendation

If you are unable to do this, then your AD is likely to be wrong. The ADR merely formalizes these questions and your answers in writing.

In fact, writing an ADR during your analysis is likely to strengthen your analysis. Often, unverbalized thoughts feel a lot more logical and consistent than they really. Having to verbalize them (it write them down) will force you to check their logic and consistency.

As early as possible

You should write your ADR before the decision is made, during your analysis, and as early as possible during the analysis phase. Consider your ADR as a working document: you create it when you realize you face an architecture decision, and fill it up gradually as you work through the relevant questions, and evaluate the relevant solutions.

After the fact, the ADR becomes purely documentation, and nobody likes writing documentation (and it's always done badly).

The primary purpose of an ADR is to communicate your analysis to others. It should be kept up to date with whatever stage your analysis is at. If you are interrupted, the task can be handed over to a colleague who will complete the analysis and the ADR, without having to redo parts of the analysis already done by you.

It also helps other stakeholders (supervisor, peers, customer) to review, if they wish, your ADR and provide corrections or suggestions.

ADR as deliverable

ADRs are accepted as deliverables, but only if they are complete, ie, they MUST include:

  • a proposed solution
  • a list of all relevant alternative solutions, properly evaluated
  • all information necessary to make an informed decision

To be accepted as a deliverable, the ADR status must be changed to Pending.

Where should I store my ADR

ADR should be stored in the project's documentation repository. ADRs are simply text documents, so they can go anywhere. However, it is best for them to be stored in a centralized repository, with collaborative and versioning features, so that everyone knows where they are and can find them easily; others can collaborate with you on the document; and it's easy to see who authored it, what are each author's contributions, and changes to the document over time.

Typically, ADRs are stored in the project's wiki (Notion, Outline), or even in the source code repo itself. ADRs can also be Google Docs.

The precise organization of ADRs (folders, sub-folders, etc.) will depend on the project. The main goal is that a particular ADR should be easy to find when needed.

ADR format

An ADR is a text document that follows a simple logical structure:

  • Title, date, name of author(s)
  • What is the issue
  • what is the proposed solution
  • what is the status of the decision
  • what is the context/background/details that lead to the proposed solution

Unless using a specific platform (Notion, Google Docs), ADRs should be written in markdown format.

Title

The title MUST be short and express in a concise and accurate manner what is the issue being decided.

The title MUST NOT include the word ADR.

Date

Format: dd MMM|MMMM yyyy

Author(s)

Who wrote the ADR.

Only include the primary author(s).

Status

Indicates the status of the Architecture Decision.

It can be one of the following:

Status Description
Draft ADR is being drafted; not ready for review or discussion
Pending ADR is ready for review and discussion. According to its author(s), it provides all the information relevant to the issue being decided
Approved Proposed solution has been approved. The ADR should not be modified after this point.
Rejected Proposed solution has been rejected. The ADR may be modified and resubmitted. It should record the fact that the initial solution was rejected.

When creating your ADR, it should be in Draft status. Change the status to Pending when you feel the ADR is ready for review and discussion. It should be complete, ie it should include:

  • a proposed solution
  • a list of all relevant solutions, properly evaluated
  • any information necessary to make an informed decision

An ADR is a deliverable only when it is in Pending status.

Issue

What is the issue being decided? What problem are you trying to solve?

This should be a short summary, just long enough to make the readers understand what you are trying to resolve.

If you need to provide further details, create a Context section further below.

Solution

What is your proposed solution? Provide enough details so that it is very clear what you intend to do and its implications.

If these details are already provided in a later section, then you can simply refer to that solution.

Context

An optional section in case you need to further explain the issue's context or background.

Solutions

A list of all relevant solutions that you evaluated.

For each solution, include a section using the following format:

Name of the solution

A description of the solution.

Pros

  • ...
  • ...

Cons

  • ...
  • ...

Consequences

  • ...
  • ...