Documenting Architecture Decisions
-->
All Topics
How We Work
Events
Customer Stories
Technology
Testing
The New Normal
Open Source
RSS Feed
Documenting Architecture Decisions
Michael Nygard<br>- November 15, 2011
agility
architecture
Context
Architecture for agile projects has to be described and defined<br>differently. Not all decisions will be made at once, nor will all of<br>them be done when the project begins.
Agile methods are not opposed to documentation, only to valueless<br>documentation. Documents that assist the team itself can have value,<br>but only if they are kept up to date. Large documents are never kept<br>up to date. Small, modular documents have at least a chance at being<br>updated.
Nobody ever reads large documents, either. Most developers have been<br>on at least one project where the specification document was larger<br>(in bytes) than the total source code size. Those documents are too<br>large to open, read, or update. Bite sized pieces are easier for for<br>all stakeholders to consume.
One of the hardest things to track during the life of a project is the<br>motivation behind certain decisions. A new person coming on to a<br>project may be perplexed, baffled, delighted, or infuriated by some<br>past decision. Without understanding the rationale or consequences,<br>this person has only two choices:
Blindly accept the decision.
This response may be OK, if the decision is still valid. It may<br>not be good, however, if the context has changed and the decision<br>should really be revisited. If the project accumulates too many<br>decisions accepted without understanding, then the development<br>team becomes afraid to change anything and the project collapses<br>under its own weight.
Blindly change it.
Again, this may be OK if the decision needs to be reversed. On the<br>other hand, changing the decision without understanding its<br>motivation or consequences could mean damaging the project's<br>overall value without realizing it. (E.g., the decision supported<br>a non-functional requirement that hasn't been tested yet.)
It's better to avoid either blind acceptance or blind reversal.
Decision
We will keep a collection of records for "architecturally significant"<br>decisions: those that affect the structure, non-functional<br>characteristics, dependencies, interfaces, or construction techniques.
An architecture decision record is a short text file in a format<br>similar to an Alexandrian pattern. (Though the decisions themselves<br>are not necessarily patterns, they share the characteristic balancing<br>of forces.) Each record describes a set of forces and a single<br>decision in response to those forces. Note that the decision is the<br>central piece here, so specific forces may appear in multiple ADRs.
We will keep ADRs in the project repository under doc/arch/adr-NNN.md
We should use a lightweight text formatting language like Markdown or<br>Textile.
ADRs will be numbered sequentially and monotonically. Numbers will not<br>be reused.
If a decision is reversed, we will keep the old one around, but mark<br>it as superseded. (It's still relevant to know that it was the<br>decision, but is no longer the decision.)
We will use a format with just a few parts, so each document is easy<br>to digest. The format has just a few parts.
Title These documents have names that are short noun phrases. For<br>example, "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP<br>for Multitenant Integration"
Context This section describes the forces at play, including<br>technological, political, social, and project local. These forces are<br>probably in tension, and should be called out as such. The language in<br>this section is value-neutral. It is simply describing facts.
Decision This section describes our response to these forces. It<br>is stated in full sentences, with active voice. "We will …"
Status A decision may be "proposed" if the project stakeholders<br>haven't agreed with it yet, or "accepted" once it is agreed. If a<br>later ADR changes or reverses a decision, it may be marked as<br>"deprecated" or "superseded" with a reference to its replacement.
Consequences This section describes the resulting context, after<br>applying the decision. All consequences should be listed here, not<br>just the "positive" ones. A particular decision may have positive,<br>negative, and neutral consequences, but all of them affect the team<br>and project in the future.
The whole document should be one or two pages long. We will write each<br>ADR as if it is a conversation with a future developer. This requires<br>good writing style, with full sentences organized into<br>paragraphs. Bullets are acceptable only for visual style, not as an<br>excuse for writing sentence fragments. (Bullets kill people, even<br>PowerPoint bullets.)
Status
Accepted.
Consequences
One ADR describes one significant decision for a specific project. It<br>should be something that has an effect on how the rest of the project<br>will run.
The consequences of one ADR are very likely to become the context for<br>subsequent ADRs. This is also similar to...