Architectural Decision Records

What are
Architectural Decisions?

Decisions that are hard to make and / or costly to change.

Software architecture is those decisions which are both important and hard to change.

Needed to fulfill quality criteria. 

High business value and / or technical risk.

Blindly accept a decision

I don't know why we do it, but i accept the decision. Maybe it was smart, i can't evaluate. Maybe not. I don't know

Blindly change it

I don't know why we do it, but i want to change it. I don't understand motivation, circumstances and consequences, and maybe i damage the project.

Without ADRs you have to ...

Without ADRs you have to ...

Without ADRs you have to ...

Sustainable Architectural Design Decisions

• Strategic: consider the long-term impact
• Measurable and Manageable: provide a measurement for the outcome over time
• Achievable and Realistic: a pragmatic decision with a good fit: neither over- nor under-engineered 
• Rooted in Requirements: built upon domain specific business drivers and constraints
• Timeless: the decision is won't be outdated soon due to technology or platform changes

Guidelines for sustainable decisions

• Use a lean/minimalistic approach for the initial decision documentation 
• Prioritize and capture all important decisions
• Change and add details when needed
• Use the right granularity level for the decision
• Use existing architectural knowledge, review and extend it
• Ensure links between decisions, designs and implementations. 
• Use proper justifications

Good 

Alternative A best meets user expectations and functional requirements as documented in user stories, use cases, and the business process model.

Poor

End users want it, but no evidence exists of a pressing business need.

Quality of Justifications

Ok, what do we need for a good Architectural Decision? 

Why & How

A short name for the Decision and the document, including the identifier, and the problem targeted

Example

ADR 1: Deployment on Ruby on Rails 3.0.10
 

or

ADR 9: LDAP for Multitenant Integration

ADR Elements: the Title

Why & How

Why we need this decision, the context and the problem that we want to solve.

Example

We want to record architectural decisions made in this project. Which format and structure should these records follow?

ADR Elements: the Context

Why & How

The drivers and forces behind the decision - technical, social, political, legal and project local.  Most of the time they are competing.

Example

• limited time to deliver solution
• pre-existing knowledge in this field
• AWS is already set as the default platform

ADR: Drivers/Concerns

Why & How

Clearly state the architecture's direction - that is, the position you've selected.

Example

We will use Github Enterprise.

ADR Elements: the decision

Why & How

Describe what alternative options that would have made sense you had a look at, too.

Example

• Gitlab SAAS
• Gitlab on premise
• Github on Premise
• BitBucket

ADR Elements: the options

Why & How

The justification why this option is the chosen one - why is this the right decision, and not any other option.

Example

• Knowledge of Github is widespread
• better support for AWS tooling

ADR Elements: the Rationale

Why & How

Make the shortcomings and negative consequences of the decision visible and known.

Example

• Risk of better support for azure than for AWS due to shared ownership
• We've already got a lot of experience using gitlab.

ADR Elements: the Downsides

Variants: the Y-Statement

Nygard

Title

Status

What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?

Context

What is the issue that we're seeing that is motivating this decision or change?

Decision

What is the change that we're proposing and/or doing?

Consequences

What becomes easier or more difficult to do because of this change?

Jeff Tyree and Art Akerman

MADRs - use parseable markup for ADRs

Y-Statements

Checklist / DoD for ADR

• Are we confident enough that this design will work?
• Have we decided between at least two options, and compared them (semi-)systematically?
• Have we discussed among each other and with peers just enough and come to a common view?
• Have we captured the decision outcome and shared the decision record?
• Do we know when to realize, review and possibly revise this decision?

Tooling

Since ADRs are text, we could ...

• Record them in GIT instead of Confluence
• use command line tools to manage them
• auto-generate documentation  & websites

Where to Start

• Links & explanations: https://adr.github.io/
• Formats, HowToStart & Examples:
  https://github.com/joelparkerhenderson/architecture-decision-record
• MADRs: https://adr.github.io/madr/
• ADR-Viewer-Tool: https://github.com/mrwilson/adr-viewer
  
• Heise-Artikel: https://www.heise.de/hintergrund/Gut-dokumentiert-Architecture-Decision-Records-4664988.html?seite=all
• Definition of Done: https://docsoc.medium.com/a-definition-of-done-for-architectural-decisions-426cf5a952b9