Establish and Document the Application's Architecture Decisions and Their Rationale

This chapter explains how to capture the significant architecture decisions made about an Application, and the reasons behind them.

Why Decisions and Their Rationale Must Be Recorded

Architecture documentation shows what an Application’s design is; it rarely shows why. Years later, a team considering a change confronts a design choice that looks odd and cannot tell whether it was a deliberate response to a constraint that still applies, or an accident that can safely be undone. Recording architecture decisions, with their context and rationale, preserves the reasoning that architecture diagrams leave out.

Establish Architecture Decision Records

Record each significant architecture decision as an Architecture Decision Record (ADR). Each ADR should capture:

• Context: the problem or situation that required a decision, and the constraints at the time.

• Options: the alternatives that were considered.

• Decision and rationale: what was decided, and why.

• Consequences: what the decision makes easier or harder, and any risks it introduces.

• Status: for example, proposed, accepted, or superseded.

When a decision is changed, record a new ADR that supersedes the old one, rather than editing the original, so that the history of the reasoning is preserved.

Document and Share Architecture Decisions

Store the Application’s ADRs in its Digital Library space or in its Code Repositories, and link them from the architecture and design documentation and from the relevant design review records. If the enterprise has a formal Enterprise Architecture organization that tracks ADRs, also register the Application’s significant decisions in Enterprise Architecture’s ADR log, so that they are visible across the enterprise.

Best Practice: Establish and Document the Application’s Architecture Decisions and Their Rationale

It is a best practice to both establish and document the solution for preserving architectural reasoning: record each significant architecture decision as an ADR with its context, options, rationale, consequences, and status, supersede rather than edit decisions that change, and register them in Enterprise Architecture’s ADR log where one exists.

Benefits: Recorded decisions let future teams understand why an Application is built the way it is, so they can change it confidently rather than either fearing to touch anything or unknowingly undoing a deliberate safeguard. Registering decisions with Enterprise Architecture lets similar decisions across Applications be compared and reused.

Advance Maturity Deliberately: Crawl, Walk, Run

• Crawl. Significant decisions are recorded in a simple, consistent format within the Application’s documentation.

• Walk. Decisions are recorded as ADRs at the time they are made, linked from design reviews, and registered with Enterprise Architecture where it maintains an ADR log.

• Run. ADRs across all Applications are searchable together and related to enterprise architecture principles and standards, so that decision patterns and recurring issues are visible.

Connections to Related IF4IT Practices and Inventories

The Solutions Architecture Best Practices and Framework addresses architecture decision-making and governance. The Enterprise Architecture Value Model describes how Enterprise Architecture adds value through decisions and their governance.