Skip to content

Latest commit

 

History

History
219 lines (155 loc) · 7.56 KB

README.md

File metadata and controls

219 lines (155 loc) · 7.56 KB
Raw

Architecture Decision Record (ADR)

ADR templates:

Introduction

An architectural decision (AD) is a software design choice that addresses a significant requirement.

An architectural decision record (ADR) is a way to track an AD, such as by writing notes, or logging information.

An architecturally significant requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture.

All these are within the topic of architectural knowledge management (AKM).

The goal of this document is to provide a fast overview of ADRs, how to create them, and where to look for more information.

Contributing

Your comments and suggestions are welcome.

You can open a GitHub issue, or create a pull request, or email joel@joelparkerhenderson.com.

Simple start

This simple start is for a typical software project. More sophisticated information comes later in this page.

  1. Create a directory for the documentation, then the architecture, then the ADR files.

Example directory names to choose from:

  ./doc/arch/adr/
  ./docs/architectures/decisions/
  ./documentation/architecture-decision-records/
  1. For each ADR, create a text file. We like to use a title that has a date and a present tense imperative verb phrase, lowercase with underscore separators, and using markdown.

Example file names:

  handle_more_users.md
  strengthen_security.md
  improve_energy_efficiency.md
  1. Write anything you want in the ADR. We like ours to cover these areas at least.

  • Title: short and action-oriented, such as "Choose a database".

  • Context: what is the issue that we're seeing that is motivating this decision or change.

  • Action: what are we proposing, or evaluating, or doing, etc.

Template ideas

ADR template by Michael Nygard, which is the simplest and most popular:

  • Title
  • Status
  • Context
  • Decision
  • Consequences
  • more detail

ADR template using Alexandrian pattern, which is simple and has context specifics:

  • Prologue (Summary)
  • Discussion (Context)
  • Solution (Decision)
  • Consequences (Results)
  • more detail

ADR template for business case, which is MBA-oriented, with costs, SWOT, and opinions:

  • Title
  • Status
  • Evaluation criteria
  • Candidates to consider
  • Research and analysis of each candidate
    • Does/doesn't meet criteria and why
    • Cost analysis
    • SWOT analysis
    • Opinions and feedback
  • Recommendation
  • more detail

ADR template by Jeff Tyree and Art Akerman, which is more sophisticated:

  • Issue
  • Decision
  • Status
  • Group
  • Assumptions
  • Constraints
  • Positions
  • Argument
  • Implications
  • Related decisions
  • Related requirements
  • Related artifacts
  • Related principles
  • Note
  • more detail

ADR template using Planguage, which is a planning language for quality assurance:

  • Tag
  • Status
  • Author
  • Revision
  • Date
  • Owner
  • Gist
  • Requirement
  • Rationale
  • Priority
  • Stakeholders
  • Risks
  • Assumptions
  • Defined
  • more detail

Additional ideas that you may want to consider overall and/or for each option:

  • Problem Definition
  • Solution Context
  • Evaluation Criteria
  • Constraints
  • High-Level Comparison Table
  • Option Description
  • Pros and Cons
  • Constraints
  • Points of Note
  • RAID log
    • Risks
    • Assumptions
    • Issues
    • Dependencies
  • SWOT analysis
    • Strengths
    • Weaknesses
    • Opportunites
    • Threats
  • Porter's 5 Forces
    • Supplier power
    • Buyer power
    • Competitive rivalry
    • Threat of substitution
    • Threat of new entry

Lifecycle

  1. Decision identification
  • How urgent and how important is the AD?
  • Does it have to be made now, or can it wait until more is known?
  • Both personal and collective experience, as well as recognized design methods and practices, can assist with decision identification.
  • Ideally maintain a decision todo list that complements the product todo list.
  1. Decision making
  • A number of decision making technqiues exists, both general ones and software and software architecture specific ones, for instance, dialogue mapping.[15] Group decision making is an active research topic.
  1. Decision documentation
  • Many templates and tools for decisison capturing exist, both in agile communities (e.g., M. Nygard's ADRs) and in traditional software engineering and architecture design processes (e.g., see table layouts suggested by IBM UMF and by Tyree and Akerman from CapitalOne.
  1. Decision enactment and enforcement
  • ADs are used in software design; hence they have to be communicated to, and accepted by, the stakeholders of the system that fund, deveop, and operate it. Architecturally evident coding styles [19] and code reviews that focus on architectural concerns and decisions are two related practices. ADs also have to be (re-)considered when modernizing a software sytem in software evolution.
  1. Decision sharing (optional)
  • Many ADs recur across projects; hence, experiences with past decisions, both good and bad, can be valuable reusable assets when employing an explicit knowledge management strategy.

Sources

Introduction:

Templates:

In-depth:

See also:

  • REMAP (Representation and Maintenance of Process Knowledge)
  • DRL (Decision Representation Language)
  • IBIS (Issue-Based Information System)
  • QOC (Questions, Options, and Criteria)
  • DRL (Decision Representation Language),
  • IBM’s e-Business Reference Architecture Framework