Documenting Architecture Decisions¶
Nygard, M. (2011). Documenting Architecture Decisions. Cognitect.
Retired. This entry was not a citation. Our extractor stored an inline prose definition from the article as though it were a bibliographic record, so its title is the name of a concept rather than of a published work. The page is kept because links to it still resolve, but it is withdrawn from the reference list. This entry is kept so the citations that pointed at it still resolve, and so the correction is visible rather than silent.
Cited by¶
15 citations across 15 artifacts.
Each citation links to the sentence it supports in the citing article.
Primes¶
- Memoing
- Software engineering. Architecture Decision Records capturing each significant decision with context, alternatives, and rationale in version control; commit messages and design docs carrying the in-flight reasoning between code-state checkpoints.
This sourceDefines the Architecture Decision Record—an append-only, dated, version-controlled record of each significant decision's context, chosen option, rejected alternatives, and rationale.
- Software engineering. Architecture Decision Records capturing each significant decision with context, alternatives, and rationale in version control; commit messages and design docs carrying the in-flight reasoning between code-state checkpoints.
Mechanisms¶
- Architecture Decision Record with Ownership
- The discipline that keeps it honest is to write at decision time, capture the alternatives that were genuinely considered, name a real owner, and keep the log append-only so the history can't be quietly tidied.
This sourceRecommends recording architectural decisions when their context is current and retaining superseded records so decision history remains inspectable.
- The discipline that keeps it honest is to write at decision time, capture the alternatives that were genuinely considered, name a real owner, and keep the log append-only so the history can't be quietly tidied.
- Architecture or Process Decision Record
- A real, named practice is Michael Nygard's Architecture Decision Record, a short document capturing the context and consequences of a significant technical decision.
This sourceIntroduces Architecture Decision Records as short text files capturing the context, decision, and consequences of significant architectural choices.
- A real, named practice is Michael Nygard's Architecture Decision Record, a short document capturing the context and consequences of a significant technical decision.
- Configuration Registry and Decision Log
- The disciplined, lightweight version of the log half is the Architecture Decision Record — capturing each significant decision together with its context and rationale, precisely so later maintainers inherit the reasoning and not just the result.
This sourceDefines an Architecture Decision Record as a lightweight record of each significant decision, its context, and its rationale for future maintainers.
- The disciplined, lightweight version of the log half is the Architecture Decision Record — capturing each significant decision together with its context and rationale, precisely so later maintainers inherit the reasoning and not just the result.
- Consistency Contract Decision Record
- Its failure mode is the failure mode of all documents: it can drift from the running system until it describes a contract nobody implements, lending false confidence.
This sourceWarns that architecture documentation loses value when it is not kept current and records when a decision has been superseded.
- Its failure mode is the failure mode of all documents: it can drift from the running system until it describes a contract nobody implements, lending false confidence.
- Decision Log
- Rather than let the reasoning live in a chat thread, they open a log entry in the lightweight Architecture Decision Record (ADR) format
This sourceDefines a lightweight Architecture Decision Record that captures the decision context, the selected response, status, and consequences.
- Rather than let the reasoning live in a chat thread, they open a log entry in the lightweight Architecture Decision Record (ADR) format
- Decision Rationale Template
- Its strength is accountability over time: it converts a decision into an auditable object, which is precisely what an Architecture Decision Record was invented to do — capture the context, the choice, and the consequences so a later engineer understands why, not just what.
This sourceNygard's ADR format records context, decision, status, and consequences so future developers can recover the motivation behind an architectural choice.
- Its strength is accountability over time: it converts a decision into an auditable object, which is precisely what an Architecture Decision Record was invented to do — capture the context, the choice, and the consequences so a later engineer understands why, not just what.
- Decision Record
- Rather than let that choice evaporate into a Slack thread, an engineer files a Decision Record in the repository, in the style of an architecture decision record.
This sourceDefines an architecture decision record as a short text file and directs teams to keep ADRs in the project repository.
- Rather than let that choice evaporate into a Slack thread, an engineer files a Decision Record in the repository, in the style of an architecture decision record.
- Decision Record Dissent Appendix
- An engineering team is choosing the primary datastore for a new platform and writes an Architecture Decision Record.
This sourceDefines an Architecture Decision Record as a short record of an architecturally significant decision, the forces behind it, and its consequences.
- An engineering team is choosing the primary datastore for a new platform and writes an Architecture Decision Record.
- Decision Record Log
- The moment they close, they write an Architecture Decision Record.
This sourceDefines an Architecture Decision Record as a record of an architecturally significant decision.
- The moment they close, they write an Architecture Decision Record.
- Decision Record with Deferred Refinement
- Modeled on the Architecture Decision Record
This sourceExplains that decision records preserve past rationale so future developers do not blindly reverse decisions and can recognize when changed context calls for revisiting longer-term intentions.
- Modeled on the Architecture Decision Record
- Proxy Retirement Decision Record
- The convention echoes the architecture decision record, whose whole value is preserving the reasoning behind a choice for the people who inherit it.
This sourceDefines an architecture decision record as a durable record of a decision, its context, and its consequences so later maintainers can understand why it was made.
- The convention echoes the architecture decision record, whose whole value is preserving the reasoning behind a choice for the people who inherit it.
- Purpose-Clause Decision Record
- Its strength is that it generalizes the Architecture Decision Record
This sourceRecords the rationale for an architectural decision while its context and reasons remain available.
- Its strength is that it generalizes the Architecture Decision Record
- Residual Complexity Justification Template
- Its lineage is the same discipline behind recording an architecture decision at the moment it is made, so the "why" survives the people who made it.
This sourceRecommends recording architecture decisions with their context and rationale so later readers can understand why they were made.
- Its lineage is the same discipline behind recording an architecture decision at the moment it is made, so the "why" survives the people who made it.
- Sub-objective Decision Record
- The form is borrowed directly from the Architecture Decision Record
This sourceIntroduces architecture decision records that preserve the rationale for a choice for later readers.
- The form is borrowed directly from the Architecture Decision Record
Verification¶
Does it exist? Not checked yet. This entry carries no identifier to resolve. It was extracted from the citation as written in the article, normalized, and deduplicated against the rest of the registry.
Does it back the claim? Not recorded. Neither this nor any other of the 15 citations of this work carries a recorded support check.
Was it audited? Yes. A second, independent pass read the citation against the article text and recorded a verdict.
Support is checked per citation rather than per work — the same source can be cited soundly in one article and wrongly in another. Per-citation recording began recently, so a citation with no recorded check is a gap in the record rather than evidence it went unchecked.
See how references were verified.
Links previously used in the corpus¶
Before the registry existed this work was also linked 2 other ways.
- https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions ×12
- https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions ×2
Registry ID ref:90d26a571847 · see in the full table