Есть в мире архитекторов программного обеспечения такое явление как ADR (Architecture Description Log - журнал архитектурных решений).
Если коротко, то это документация, в которой в формате .md (markdown) подробно фиксируется каждое архитектурное решение, принятое на проекте.
Есть строго установленные требования к каноническому ADR:
1) к формату текста (.md и не что иное, кроме)
2) к доступности журнала (должен находиться в git-репозитории)
3) к содержимому журнала. Оно должно быть достаточно подробным:
- какое решение
- когда
- кем
- почему было принято
- рассмотренные альтернативы с их плюсами и минусами.
Также бытует мнение, что без канонического ADR на проекте нет и не быть не может архитектуры, а есть лишь толко хаос.
Когда изучал эту тему, у меня, кроме восторга от получения новых знаний, появился и ряд вопросов к этому явлению (кто, когда, как и зачем):
1. Кто ведёт ADR?
2. Когда он это делает?
3. Как, с помощью каких удобных инструментов он это делает?
4. Зачем он это делает?
Примеряя на себя роль архитектора, я попробовал вести ADR на одном из новых проектов, на котором участвовал в качестве одного из "архитекторов без снижения активности в разработке". Вот, как я ответил себе на вышеуказанные 4 вопроса:
1. Кто будет вести ADR?
Это должен быть архитектор, у которого ведению ADR должно быть посвящено его основное рабочее время. Он же не будет архитектором одного проекта -значит, ему нужно будет принимать решения и вести ADR на многих проектах.
Конечно же это я: сам придумал - сам и делай. А остальные потом поймут удобство и важность того, что я делаю и присоединятся к ведению ADR.
2. Когда я буду вести ADR?
В своё основное рабочее время? Нет активности по разработке никто не отменял. Плюс, к ней добавились архитектурные активности - бесконечные совещания и обсуждения на тему "а давайте угадаем, чего заказчик может захотеть вот тут через год" и "давайте решим за заказчика, как ему будет удобнее" и попытки убедить коллег по цеху в том, что ничего придумывать за заказчика не надо (но это уже дугая история).
Учитывая это, следуюшие активности пришлось перенести на нерабочее время (переработки за свой счёт):
- обсуждение архитектурных решений (да-да, совещаемся в рабочее время, а программирование нагоняем потом, после работы),
- ведение ADR,
- изучение архитектруных вопросов,
- проверка гипотез,
- контроль за соблюдением архитектурных решений на проектах.
Сказать разработчику, что он теперь архитектор, но без снижения активности в разработке, и все активности должны выполняться в рабочее время с 09:00 до 18:00 - это всё равно, что попросить сделать 12 шапок из шкуры 1 овцы.
Чтобы не забыть ничего важного, видео "архитектурных" совещаний записывал и пересматривал при ведении ADR, уже после работы. Во время самих совещаний слушал коллег в полуха и вмешивался только когда слышал, что собирается произойти уж совсем что-то непотребное.
3. Как, с помощью каких удобных инструментов я буду вести ADR?
Таких инструментов нет, чтоб: набирать текст как в текстовом редакторе, форматировать, вставлять картинки, схемы, таблицы, а оно сохранялось бы как текст в формате .md. Ну, или я плохо искал.
Чтобы ADR был доступен в режиме чтения-записи и менеджерам, и аналитикам, и разработчикам, и тестировщикам, решил вести его в Confluence (инструмент, принятый в компании для ведения разного рода документации) и, естесственно, не в формате markdown.
4. Зачем нужен ADR на этом конкретном проекте?
Согласно теории, ADR нужен для того, чтобы в любой момент вермени можно было найти мотивированные ответы на вопросы:
- почему мы сделали именно так, а не иначе,
- если что-то пошло не так - мы можем применить что-то другое, вместо того, что есть.
Это очень удобно и правильно. И спорить в полезности таких записей - глупо.
Что вышло на самом деле:
Аналитик: "Я же уже записал принятые решения в конфлюенсе, только нетак подробно с точки зрения архитектуры, не разбивал на разделы и не описал недостатки других решений. Зачем дублировать? Можешь это пренести на мою страницу конфлюенса? Я не хочу писать изменения сразу на нескольких страницах. А изменения есть, потому что то, что ты записал, мы обсуждали вчера, а сегодня заказчик сказал (написал email), что мы его неправильно поняли и надо всё подкорректировать".
Прав аналитик? Прав. Зачем дублировать, если это его работа - описать реализацию требований заказчика. И не прав. Потому, что то, что описывает аналитик - это не канонический ADR.
Так как я не участвую во всех совещаниях аналитика с заказчиком, не читаю их переписку и не могу в режиме нон-стоп отслеживать все изменения, внесённые аналитиком в описание функциональных требований, ADR будет неизбежно отставать от функциональных требований и перестанет быть источником истины, куда все будут ходить за ответами. В итоге, ведение ADR будет просто отнимать моё личное время, не принося никакой пользы проекту.
Вот так, полным фиаско, закончилась моя идея с ведением ADR на новом проекте в качестве "господина архитектора-разработчика".
Был ещё один проект с ADR, в котором я участвовал уже как просто разработчик, без функций "архитектора". На этом проекте канонический ADR вёлся по всем правилам человеком с должностью "архитектор". Мне не известно ни о качестве этого ADR, ни о его соответствии реальному положению дел на проекте, так как я только ознакомился с внешним видом журнала в git-репозитории, не читал его содержимое и тем более не сравнивая с кодом приложений на проекте.
У это проекта давным-давно "сгорели все сроки" и меня привлекли как "тяжёлую артиллерию", чтобы помочь вытащить проект из 1,5-годовой "долговой ямы". Поэтому времени на "целование манжетов" с ADR уже не было. Насколько я знаю, времени на это не було ни у аналитиков, ни у разработчиков, ни у тестировщиков, ни у менеджеров этого проекта. Многие из них просто не умели пользоваться git-ом и непонимали, как работать с форматом markdown.
Лично у меня сложилось мнение, что канонический ADR - это вещь в себе. Необходимо или как-то адаптировать его под нужны проекта, или постфактум срисовывать с того, что описали аналитики в функциональных требованиях, попутно дополняя техническии деталями.