Реестр архитектурных решений

Architecture decision record (ADR) / Architecture decision log (ADL) — это регулярная фиксация принятых и непринятых в ходе разработки программного обеспечения решений, затрагивающих дизайн, проектирование, выбор инструментов и подходов, и отвечающих определенным функциональным или нефункциональным требованиям. Вместе с решением фиксируется его контекст, последствия и альтернативы, из которых делался выбор.

Цель: повышение качества решений в будущем, снятие вопросов типа "Почему сделано именно так и не сделано вот так", которые возникают у нового сотрудника.

Проблемы, решаемые проектным офисом

Такие же, как фиксации знаний в целом

Фиксация знаний помогает:

онбордингу новых разработчиков
вникать в незнакомые части проекта
саппорту, отладке
проектированию и принятию решений
онбордингу конечных пользователей продуктов

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

== Фундаментальные проблемы всех практик фиксации знаний

При внедрении практик фиксации знаний, knowledge manager-ы сталкиваются последовально с тремя проблемами:

Почти никто не делает записей
Мало кто читает сделанные записи
Записи устарели / ошибочны — об этом знают, но не исправляют

=== Фиксация

Вложения в фиксацию знаний должны окупаться, нужно найти баланс между гибкостью и документированностью
Людей нужно приучить в нужный момент заниматься фиксацией
Людей нужно научить правильно делать записи (к примеру, многие боятся заниматься документированием, так как не умеют писать тексты)

=== Чтение

Нужно научить людей в нужный момент читать записанное
Нужно сделать так, чтобы люди знали, как в нужный момент найти записанное

=== Исправление

Исправляемость зафиксированной информации — это важный критерий всех практик документирования.

Людей очень сложно приучить исправлять чужие тексты, и, как правило, до проблемы с исправлением старых документов мало кто дорастает.

Вот ряд проблем:

Устаревание информации
Дублирование информации
Не понятно, куда и как вклинить свои правки
Не понятно, как проводить рефакторинг зафиксированных документов
Нет реальных ответственных за документы

Как выбрать уровень детализации? Слишком глубокая детализация никогда не будет поспевать за реализацией и будет слишком дорогой, а поверхностное описание архитектуры ничем никому не поможет.

Как построить документационную культуру и сформировать привычку фиксации?

Кого назначить ответственным за описание архитектуры?

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

С чего начать внедрение этого изменения

Продумайте процесс, в какой момент и кто должен делать запись в реестре. Пропишите этот шаг в процессе.
Соберите встречу всех solution архитекторов, старших разработчиков и менеджеров, на которой нужно донести, что теперь при проектировании будущей архитектуры разработчик или архитектор должен выложить набор альтернатив и выбраных решений в версионное хранилище.
Выберите инструмент для ведения и создайте шаблон описания каждого решения.
Напишите первый ADR и дайте кому-нибудь поревьюить.

Можно вести такой реестр в:

Google Sheet/Doc;
репозитории проекта в папке /doc/adr/;
вашей вики;
Jira (вашем тикет-трекере), тогда стоит завести отдельную очередь.

Вот несколько готовых шаблонов ADR:

и примеры уже описанных архитектурных решений.

Также посмотрите выступление David Ayers по теме Communicating and documenting architectural decisions на конференции LeadDev, где он рассказывает про социализацию принятых решений и легковесные реестры архитектурных решений, начиная с третьей минуты.

Запуск пилотного проекта

Пусть вашим первым решением будет "Мы будем вести ADR".

ADR должен быть:

Написан простым прямым языком;
Кратким, максимум на 1 страницу для каждого решения;
Написан в простой разметке, вроде маркдаун, и храниться рядом с кодом.

Пример:

# ADR N: Краткое название решения

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

## Решение

Опишите ваш ответ на обстоятельства, пишите полными предложениями в активном залоге, например, "Мы сделали ...".

## Статус

[Предложено | Принято | Устарело | Заменено]

если устарело, напишите обоснование. Если заменено, приведите ссылку на новое.

## Последствия

Опишите, что произошло после принятия решения, последствия, как положительные, так и отрицательные.

Масштабирование успеха

CLI-инструмент для ведения ADR прямо в репозитории проекта.
Добавить как задачу в бэклог или добавить проверки наличия ADR в CI.
Создать шаблоны, они должны быть готовы к использованию.
Проводить peer-review записей.

Что может пойти не так

Вы забросите ведение реестра, будете вести его нерегулярно;
Если в него периодически не заглядывать, есть вероятность повторения ранее отброшенных вариантов решения.

archirecture, decisions, documentaition