Architecture Decision Records.

Just a decorative image for the page.

TL;DR

Architecture Decision Records (ADRs) are a lightweight tool to document your decisions. They were invented by Michael Nygard in 2011. ADRs help you, your team and a potential successor to understand why something has been built in a certain way.

ADRs are a great tool to think about potential pros and cons. They help to decide on a course of action jointly with your team and stakeholders.

The Problem

If you are an engineer then you know the feeling when you are coming to an older software system: “Wow! This looks really strange - why has it been done that way???”. My initial reaction is always very childish and I assume that the creators were incompetent. But that is of course never true. It’s just me being stupid.

Software looks the way it looks like for very good reasons. Business, technology and people all have a significant impact.

If we don’t know about these reasons then at least two bad things will happen:

  • We’ll have a hard time understanding why a system has been built in a certain way
  • We’ll repeat the same mistakes again

Ouch.

A Solution

Architecture Decision Records for the rescue!

ADRs are an awesome and lightweight tool to document your decisions. This makes it very easy for you and your successors to read about decisions. It makes sure you do not repeat the same mistakes again (“Ah - now I know why they did it that way - damn - I have to roll back the changes of the last two weeks”).

ADRs support you in two key areas.

  1. A proper architecture decision will need written documentation and properly summing up pros and cons. This also facilitates the discussion with your team and stakeholders. ADRs are exactly that: A nice writeup of architecture decisions ready for discussion.
  2. They allow to travel back in time. You can re-read why something has been decided in a certain way. This not only helps the next generations of engineers, but also you to not repeat mistakes and learn from the past.

How ADRs Look Like

Architecture Decision records were invented by Michael Nygard in 2011. They are - on purpose - very simple and have a title and 4 sections.

  • Context: Background on this decision. Why we talk about it. Pros and cons.
  • Decision: What has been decided and why.
  • Status: A status like “accepted, rejected, proposed…”
  • Consequences: What is the outcome. Anything that will be easier? Any downsides we accept?

An Example

Here’s an example of an Architecture Decision Record:

# Context
Our current database system does not allow extended join operations 
needed for our upcoming business use cases.

## Options

### We can keep our database system and do the joins manually in our applications
#### Pros
- No new database system
- Everything stays the way it is

#### Cons
- A lot more logic and complexity in our applications
- Performance can be critical

### We could move to a different database system like FooDB that supports these joins
#### Pros
- Logic in code stays simple. Joins are also simple to express in SQL.
- Database system has many more advantages that could be beneficial in the future

#### Cons
- All applications on our side have to move to new database driver
- There might be incompatibilities that we only find out when running the apps
- We understand our old database system perfectly fine (Ops, developers)

# Decision
We'll move to FooDB. It supports all join types we need and is in active 
development. Moving the data will incur a minimal downtime. The database system 
can also run on AWS which means we don't have to do the maintenance and operation 
any more. We'll gradually roll out the changes to user cohorts step by step so 
that we can find bugs and minimize the impact.

# Status
ACCEPTED

# Consequences
- We have to use different database drivers to access the database
- A workgroup been set up to move the data
- Ops team will support the move and take over operation on AWS

Additional Tooling

There’s some additional tooling at https://github.com/npryce/adr-tools. In my opinion you do not really need it. Any wiki or git repo with markdown files will be perfect. Just start with it. Use the structure with four sections (Context, Decision, Status, Consequences) and order them.

Conclusion

Architecture decision records are a great tool to facilitate thinking about architecture. Avoid using it at your own peril!

More

Imprint | Privacy Policy