adr.github.io Open in urlscan Pro
2606:50c0:8001::153  Public Scan

Form analysis
0 forms found in the DOM

Text Content

View on GitHub


ADR.GITHUB.IO


HOMEPAGE OF THE ADR GITHUB ORGANIZATION


ARCHITECTURAL DECISION RECORDS (ADRS)

An Architectural Decision (AD) is a justified software design choice that
addresses a functional or non-functional requirement that is architecturally
significant. An Architecturally Significant Requirement (ASR) is a requirement
that has a measurable effect on a software system’s architecture and quality. An
Architectural Decision Record (ADR) captures a single AD and its rationale; the
collection of ADRs created and maintained in a project constitute its decision
log. All these are within the topic of Architectural Knowledge Management (AKM),
but ADR usage can be extended to design and other decisions (“any decision
record”).

The aim of the GitHub adr organization is to:

 1. Motivate the need for and benefits of AD capturing and establish a common
    vocabulary
 2. Strengthen the tooling around ADRs, in support of agile practices as well as
    iterative and incremental software engineering processes
 3. Provide pointers to public knowledge in the context of AKM and ADRs

The repository for the Website of the ADR organization is
https://github.com/adr/adr.github.io.


ADRS IN THE MEDIA

 * Love Unrequited: The Story of Architecture, Agile, and How Architecture
   Decision Records Brought Them Together, Michael Keeling in the Pragmatic
   Designer column of IEEE Software Vol. 39 Issue 4 (2022) (PDF)
 * Chapter 3 of “Patterns for API Design: Simplifying Integration with Loosely
   Coupled Message Exchanges” in the Addison Wesley Signature Series at Pearson
   features six narratives guiding through the conceptual level of API design:
   29 recurring decisions with options and criteria. Learn more in this blog
   post.
 * Architectural decision capturing is positioned as one of the essential
   activities in Design Practice Reference, a LeanPub e-Book.
 * (German) Gut dokumentiert: Architecture Decision Records by @obfischer
   published at heise online.


LIGHTWEIGHT ADRS SHOULD BE ADOPTED

A “lightweight” ADR consists of title, status, context, decision, and
consequences (according to @mtnygard). ThoughtWorks listed architectural
decision records as “adopt” at their technology radar vol. 18:
https://www.thoughtworks.com/en-us/radar/techniques/lightweight-architecture-decision-records

We think that the considered options with their pros and cons are crucial to
understand the reason of a chosen option. MADR — The Markdown Any/Architecture
Decision Records (MADR: [ˈmæɾɚ]) in this ADR organization includes such tradeoff
analysis information.


RELATION OF ADRS, MADR, AND OTHERS




SUSTAINABLE ARCHITECTURAL DECISIONS

We base our work on the guidelines and principles in Sustainable Architectural
Decisions by Zdun et al., for instance the Y-statement format suggested in that
article. However, we are open to other formats of ADRs as shown at
@joelparkerhenderson’s repository.

In short, the Y-statement is as follows:

> In the context of <use case/user story u>, facing <concern c> we decided for
> <option o> to achieve <quality q>, accepting <downside d>.

The long form of it is as follows (extra section “because”):

> In the context of <use case/user story u>, facing <concern c> we decided for
> <option o> and neglected <other options>, to achieve <system qualities/desired
> consequences>, accepting <downside d/undesired consequences>, because
> <additional rationale>.

You can find more explanations and examples on Medium Y-Statements - A Light
Template for Architectural Decision Capturing.

A Definition of Done for Architectural Decision Making proposes five criteria
and a checklist to decide when it is time to set the status of a single decision
to “done”: evidence, criteria and alternatives, agreement, documentation, and
realization/review plan. Here, we focus on the ‘D’ in ecADR.


EXISTING ADR TEMPLATES

 * Overview: Architectural Decision Records: collection of markdown templates
   converted to Markdown
 * MADR: The Markdown Architecture Decision Records (MADR: [ˈmæɾɚ]). Lean ADRs
   to quickly document architectural decisions in code. - Slogan: architectural
   decisions that matter [ˈmæɾɚ].
 * Comparison of seven templates: Architectural Decision Guidance Across
   Projects - Problem Space Modeling, Decision Backlog Management and Cloud
   Computing Knowledge. WICSA 2015: 85-94.
 * Context, background and examples of good and bad justifications can be found
   in this blog post.
 * DecisionCapture: Templates for agile projects and explanation of the ADR
   universe, with example.
 * cards42 has adopted the Y-statement template in its German ADR card; the
   English version is similar, but adds state information.
 * The template for ISO/IEC/IEEE 42010:2011, the international standard for
   architecture descriptions of systems and software, suggests nine information
   items for ADRs its Appendix A. It also identifies areas to consider when
   identifying key decisions.


GOOD ADRS (AND HOW TO GET TO THEM)

 * How to create ADRs — and how not to collects good practices and anti-patterns
 * Architectural Significance Test and Some Core Decisions
 * The Markdown ADR (MADR) Template Explained and Distilled
 * Proposal for A Definition of Done for Architectural Decision Making
 * How to review ADRs — and how not to has good practices, anti-patterns, review
   check list


DECISION CAPTURING TOOLS

Disclaimer: The following list is rather inclusive. Please find out about the
status and the maturity of the list entries for yourself by following the links.
We are happy to include more candidate assets here.

 * adr-manager: Craft MADR 2.x templates directly in the Web Browser.
 * adr-tools - bash scripts to manage ADRs in the Nygard format. example.
   * Ansible script to install adr-tools: ansible-adr-tools
   * C# rewrite: adr-cli
   * Go rewrite: adr
   * Java rewrite: adr-j
   * ESM Node.js port: adr-tools
   * Node.js rewrite: adr
   * PHP version: phpadr
   * Powershell module: adr-ps
   * Python rewrite: adr-tools-python
   * Another Powershell module: ArchitectureDecisionRecords
 * adr-viewer - python application to generate a website from a set of ADRs.
 * architectural-decision: PHP library to create ADRs using PHP8 Attributes.
 * Embedded Architectural Decision Records, which shows how a distributed AD log
   can be embedded in Java Code via ADR annotations.
 * Log4brains: CLI and web UI to log and publish your ADRs as a static website
 * Loqbooq: Web App with Slack integration to record ADR-inspired decision logs
 * Talo: CLI (and dotnet tool) to manage and export ADRs, RFCs and custom
   software design document types.


TOOLING RELATED TO ARCHITECTURE MANAGEMENT

 * ArchUnit: unit tests for architecture
 * docToolchain: docToolchain is an implementation of the docs-as-code approach
   for software architecture plus some additional automation.
 * Structurizr: Structurizr is a collection of tooling to help you visualise,
   document and explore your software architecture using the C4 model.


INTERESTING, BUT UNMAINTAINED TOOLING

 * adr-log: Generates an architectural decision log out of MADRs.
 * ADMentor Architectural Decision Modeling Add-In for Sparx Enterprise
   Architect
 * eadlsync: Synchronizes embedded architectural decision records with a
   repository of architectural decisions.
 * SE Repo: Software Engineering Repository. A repository for versioning
   software engineering artifacts, which can be architectural decisions,
   patterns, and others.


MORE INFORMATION

 * “An Adoption Model for Architectural Decision Making and Capturing”
 * Architectural Decisions — The Making Of - provides some history on
   architecture decision records.
 * Architectural Decision Records (ADR): Open & Transparent Decision History in
   the Open Practice Library
 * An AWS Prescriptive Guidance recommends using architectural decision records
   to streamline technical decision-making for a software development project.
 * Architectural Knowledge Management (AKM) overview at OST
 * Documenting Architecture Decisions by Michael Nygard
 * Architecture Decision Records in Action by Michael Keeling (IBM Watson Group)
   and Joe Runde (IBM) [YouTube] - presentation including empirical numbers.
 * Documenting Architecture Decisions - Blog entry by Fabian Keller
 * From Architectural Decisions to Design Decisions and ADR = Any Decision
   Record? - two blog posts by Olaf Zimmermann proposing to extend the scope of
   ADRs.
 * Method selection and tailoring in DPR, the Design Practice Repository (DPR)
   on GitHub and the Design Practice Reference, a corresponding LeanPub e-Book.
   Architectural decision capturing is positioned as one of the essential
   activities in DPR.


CONTRIBUTE

To improve this page, head to https://github.com/adr/adr.github.io, edit
index.md, and submit a pull request.

adr.github.io maintained by adr

Published with GitHub Pages