Guidelines for Documenting Architectural Decisions

Given the context of evolvable software architecture and agile projects, documentation must be concise, clear, effective and… constantly changing. Nobody wants to stare at big walls of text in long software design document just to figure out the information is outdated.

Photo by Brett Jordan on Unsplash

Moving fast, experimenting often or pivoting on ideas requires quick decisions.

Decision making is a cognitive process resulting in the selection of a belief or a course of action among several possible alternative options.

In software engineering we strive to avoid any irrational aspect that could influence our decision making process. Another important aspect is that most often our decisions are part of a complex adaptive system and are highly contextual and temporal. Failing to document decisions can negatively affected the software development process and force engineers to either blindly accept the decision or to blindly change it. Therefore the need to documenting architectural decisions in the right ways is very real.

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 might, for instance, be a technology choice (e.g., MySQL vs. MongoDB), a choice of the IDE (e.g., IntelliJ vs. Eclipse IDE), a choice between a library (e.g., SLF4J vs java.util.logging), or a decision on features (e.g., infinite undo vs. limited undo). Any decisions that might have an impact on the architecture somehow are architectural decisions.

Sustainable Architectural Design Decisions

There are five characteristics of a sustainable architectural design decision:

  1. Strategic – consider strategic consequences and long-term impact.
  2. Measurable and manageable – the decision’s outcome should be measurable over time according to objective criteria.
  3. Achievable and realistic – the rationale for fitting the solution to the problem should be chosen pragmatically and made explicit.
  4. Rooted in requirements – company environment, requirements, constraints in development team size and skills should be considered.
  5. Timeless – decisions should be based on experience and knowledge that won’t likely be soon outdates.

PRILER checklist

A decision has many aspects we must think of. One way to help identify significant decisions early and manage them is to adopt a mindset for quickly analysing decisions.

The PRILER checklist is a nice way to force decision makers to focus on all aspects of a decision. The purpose of applying the PRILER checklist is to identify significant decisions and to collect the right information.

Good Architectural Decision Records

  • An ADR must be concise but include
    • title
    • context including related technical or functional details
    • problem statement
    • timestamp
    • who’s involved
    • status (proposed | rejected | accepted | deprecated | … | superseded by <ADR>)
    • what follows from making the decision
    • why was this decision made
    • how will this impact – both positive impact and negative impact must be documented.
  • One ADR documents a single decision.
  • ADRs should be immutable. If a new architectural decision was made that affects a previous ADR, the new ADR should be created and should reference the existing one.

High cohesion between context and scope

Technical documentation that focuses on the code should stay close to the code. High cohesion between code and documentation increased chances that software engineers will keep the documentation in sync with the code changes in ever changing code bases.

A simple and effective way to document design decisions is to use ADRs and keep them in the version control system with the source code.

One disadvantage of keeping ADRs in the VCS is that it may make them harder to find by non-technical stakeholders. But this aspect can be improved with the right tooling.

ADR tooling

As Markdown is widely used as the de-facto markup language in software projects, it would make perfect sense to use it to document ADR.

Markdown Any Decision Records (MADR) is a lean template to capture any decisions in a structured way, using Markdown. The template originated from capturing architectural decisions and developed to a template allowing to capture any decisions taken.

Another argument for Markdown is that there are a plethora of tools developed for and around Markdown that can be use to run static analysis on ADR files or transform them to other formats.

Check out my repo if you need a starting point with these tools.

ADR templates

Depending on the type of the project one template could be more suited than other. Check out this link for a nice collection of ADR templates.


Decision making is a cognitive process. An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. Sustainable architectural decisions. Any decisions that might have an impact on the architecture are architectural decisions. Decision makers should aim for sustainable architectural decisions. The PRILER checklist can help in identifying significant architectural decision. A minimalistic decision documentation is preferred and Markdown is an easy to use format and way of keeping it close to code.