shangxiao / ADR-template

A md template for Architecture Decision Records (ADRs)

ADR template

Markdown template for Architecture Decision Records (ADRs). Here's the template...

• Template in English
• Template in Spanish
• Template in Chinese
• Template in Portuguese

Usage guidelines

• Each ADR is a plain text, 1-2 page document
• ADRs should be numbered
• ADRs should be stored within each software project repo
• Create a separate repo for crosscutting ADRs
• Track ADRs in the backlog
• Review ADRs
• Create ADRs for significant design decisions
• This template is a suggestion that you may want to adopt or adapt. In any case, establishing and sharing a template for ADRs in your team or organization is a good idea.

Examples of ADRs using this template

• Use of the BFF pattern
• Use CQRS
• Use AWS as cloud provider
• Use Payment Gateway in self-hosted mode
• Use the Wrapper pattern

(These examples are project-specific, of course. The decision and rationale make sense in that project's context.)

References

This template is based on:

• Documenting Architecture Decisions. Blog post by Michael Nygard, 2011.
• Architecture Decision Records in Action. SATURN 2017 presentation by Michael Keeling and Joe Runde.

See also this post and conference presentation by Ken Power.

Why this template?

• This template addresses a subtle yet fundamental deficiency of the ADR structure originally proposed by Michael Nygard:
  his proposed structure (Context; Decision; Status; Consequences) has no evident placeholder for the rationale behind the design decision.
• The justification, the rationale, the "why" behind the design decision should stand out as a separate section in the template for at least three reasons:
  • It is remarkably important! (Authors cited further below agree.)
  • A separate section reminds the author of the ADR that that information must be captured.
  • The rationale section avoids cluttering other sections with rationale discussion. Devs may reference the ADRs several times to re-read the decision and consequences. They need to read the rationale just once, so rationale should not be mixed in the other sections.
• Mark Richards and Neal Ford say "Why is more important than how" is the Second Law of Software Architecture (Fundamentals of Software Architecture).
• We say in our book "Record Rationale" is Rule 5 of the Seven Rules for Sound Documentation (Documenting Software Architectures, Second Edition).
• George Fairbanks proposed Architecture Haiku, which can be seen as an alternative approach to ADR. Haiku contents includes "design rationales".