Статьи серии:

Architectural Decision Records (ADR)
Architectural Decision Records (ADR). Y-Statements

AD и ADR

Что такое AD и ADR?

Architectural Decision (AD) - Архитектурное решение. Решение (выбор) принятое в процессе разработки архитектуры или проектирования программного обеспечения.

Architectural Decision Records (ADR) - Документ описывающий архитектурное решение.

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)

источник

Главное из этого описания:

• архитектурное решение - это выбор технологии, подхода и т.п.
• архитектурное решение оказывает значительное влияние на архитектуру
• нефункциональные требования являются причиной появления архитектурного решения
• ADR содержит (описывает) только одно архитектурное решение
• коллекция решений (ADR) - это журнал принятия решений описывающий проект, систему, компонент

Важно: Архитектурное решение (AD) или ADR - это не решение (solution) для имплементации какой-либо фичи, бизнес требования и т.п. Solution может включать в себя столько ADR сколько выборов необходимо было сделать в процессе разработки solution'а.

Или вот еще одно пояснение, что такое ADR:

An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. This might, for instance, be a technology choice (e.g., Java vs. JavaScript), a choice of the IDE (e.g., IntelliJ vs. Eclipse IDE), a choice between a library (e.g., SLF4J vs java.util.logging), or a decision on features (e.g., infinite undo vs. limited undo).

источник

Зачем?

ADR - это максимально простой документ отвечающий на вопрос, почему было принято то или иное решение.

ADR - это текстовое описание принятого решения, которое позволяет выразить заметно больше чем через диаграммы. Является прекрасным дополнением для различных диаграмм, поясняя почему и как было принято то или иное решение.

ADR - это не только текст. Нет запретов на использование диаграмм в ADR если это уместно и поможет описать мысль яснее.

Где записывать?

Подойдет любой инструмент с функциями поиска, версионирования, организации документов. Например, Confluence или Git.

Ниже приведен пример формата записи для хранения в Git.

Когда стоит записать решение?

В статье с хабра есть отличный пример критериев, когда стоит записать принятое решение. Его можно использовать как драфт вашего собственного списка критериев:

• структуру ПО;
• функциональные характеристики ПО;
• зависимости между компонентами (где мы допускаем сильное связывание, а где его не должно случиться);
• интерфейсы и API (как наши компоненты, модули и прочее будут взаимодействовать друг с другом);
• используемые технологии (платформы, фреймворки, тулы и так далее).

Как писать?

Писать нужно просто, понятно, коротко. Чтобы потом не приходилось делать презентации с описанием и интерпретацией написанного в ADR.

Интересная статья о том как писать ADR с хорошими и плохими подходами: How to create Architectural Decision Records (ADRs) — and how not to

И еще пару статей:

Architectural Significance Criteria and Some Core Decisions Required
A Definition of Done for Architectural Decision Making
How to review Architectural Decision Records (ADRs) — and how not to

MADR

Что это такое?

MADR - "Markdown Any Decision Records" (MADR). Ранее был известен как "Markdown Architectural Decision Records" (MADR). это Architectural Decision Records записанный в формате markdown.

MADR (https://adr.github.io/madr/) is a lean template to capture any decisions in a structured way.

В Short Version выглядит это примерно так:

# Какой фреймворк выбрать для создания нового UI компонента

## Контекст и постановка проблемы

Нужно сделать новый дашборд в существующей системе.
Нужно сделать быстро.

## Рассмотренные варианты

* React
* Angular
* Blazor

## Результат принятия решения

Был выбран React так как для него существует UI компонент Х с хорошей функциональностью из коробки.

Есть еще Long Version, где предлагается довольно подробно описать решение. Выглядит привлекательно.

Markdown удобен тем, что это текст который можно хранить в git, его можно прочитать и без рендеринга, существует много инструментов работы с ним.

Шаблоны MADR

ADR Template
adr-template-long.md
adr-template-long-ru.md

И еще немного шаблонов из репозитория joelparkerhenderson/architecture-decision-record:

• Decision record template by Jeff Tyree and Art Akerman
• Decision record template by Michael Nygard
• Decision record template for Alexandrian pattern
• Decision record template for business case
• Decision record template of the MADR project
• Decision record template using Planguage
• Decision record template by Paulo Merson
• Decision record template by EdgeX
• Decision record template by Olaf Zimmermann (!!! medium.com !!!)

Инструменты для работы с MADR

Для того чтобы сделать работы с коллекцией решений более удобной мы можем использовать такие инструменты как:

• ADR Manager - облегчает работу с коллекциями ADR в Github.
• Log4brains - Log4brains is a docs-as-code knowledge base for your development and infrastructure projects.

Еще несколько инструментов можно найти тут.

Интересное

The Markdown ADR (MADR) Template Explained and Distilled
Architectural Decision Records (ADRs)
madr-paper9.pdf

Заключение

История принятых решений в том виде и объеме в котором эти решения доносились до команды - это отличный способ увеличить прозрачность в проекте.