Задать вопрос Поделиться знаниями Редактировать страницу

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

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

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

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

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

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

  • Онбордингу новых разработчиков

  • Вникать в незнакомые части проекта

  • Саппорту, отладке

  • Проектированию и принятию решений

  • Онбордингу конечных пользователей продуктов

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

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

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

  • Никто не делает записей

  • Никто не читает сделанных записей

  • Записи устарели / ошибочны, об этом знают, но не исправляют

=== Фиксация

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

  • Людей нужно приучить в нужный момент заниматься фиксацией

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

=== Чтение

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

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

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

Вообще говоря, исправляемость зафиксированной информации — это важный критерий практик документирования вообще.

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

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

  • Устаревание информации

  • Дублирование информации

  • Не понятно, куда и как вклинить свои правки

  • Не понятно, как проводить рефакторинг зафиксированных документов

  • Нет реальных ответственных за документы

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

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

  1. Продумайте процесс, в какой момент и кто должен делать запись в реестре. Пропишите этот шаг в процессе.

  2. Соберите встречу всех solution архитекторов, старших разработчиков и менеджеров, на которой донести, что теперь при проектировании будущей архитектуры разработчик или архитектор должен выложить набор альтернатив и выбраных решений в версионное хранилище.

  3. Выберите инструмент для ведения и создайте шаблон описания каждого решения.

  4. Напишите первый adr и дайте кому-нибудь поревьюить.

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

  • В Google Sheet/Doc;

  • В репозитории проекта в папке /doc/adr/;

  • В вашей вики;

  • В Jira (вашем тикет-трекере), тогда стоит завести отдельную очередь.

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

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

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

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

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

  • Написан простым прямым языком;

  • Кратким, максимум на 1 страницу для каждого решения;

  • Написан в простой разметке, вроде маркдаун, и храниться рядом с кодом.

Пример:

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

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

## Решение

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

## Статус

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

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

Последствия

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

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

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

  • Вы забросите ведение реестра, будете вести его нерегулярно;

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

archirecture, decisions, documentaition

Лицензия Creative Commons | by Igor Tsupko, Lana Novikova, Rodion Nagornov & community