С того момента, как я взял на себя роль технологического архитектора, мне стало интересно, почему были приняты определенные решения вместо других вариантов.
Диаграммы Visio - это здорово, но это не что иное, как картинки. Они не рассказывают вам историю того, почему определенные стрелы идут в определенном направлении, а не в обратном.
Технологический радар ThoughtWorks
Пытаясь решить эту дилемму, я наткнулся на последнюю редакцию ThoughtWorks Technology Radar.
«Мы компания-разработчик программного обеспечения и сообщество увлеченных и целеустремленных людей. Мы думаем о подрывной разработке технологий для решения самых сложных задач наших клиентов, стремясь при этом произвести революцию в ИТ-индустрии и добиться позитивных социальных изменений ». - ThoughtWorks
В радаре технологий ThoughtWorks публикует новости о том, что вам следует использовать, что вы должны продолжать делать и что вы можете попробовать.
ThoughtWorks рассказывает о различных:
- Техники
- Платформы
- "Инструменты"
- Языки и фреймворки
Читая раздел о методах, я заметил, что ThoughtWorks рекомендует использовать Записи о решениях облегченной архитектуры (LADR).
Я не знал о LADR, поэтому начал исследовать.
История LADR
Исследуя LADR, я наткнулся на очень интересную статью Майкла Найгарда. В статье рассказывается о методе встраивания документации по архитектуре как части самого кода.
Цитата из статьи:
Архитектуру Agile-проектов нужно описывать и определять по-другому. Не все решения будут приняты сразу, и не все они будут приняты, когда проект начнется. - Майкл Найгард
Это правда. Agile широко используется, и должен быть определенный процесс, охватывающий все архитектурные решения. Часто мы создаем большое количество документации, которую никто не любит читать.
По мере того, как я читал больше, я нашел лучший способ документировать ваши решения.
Git Friendly
ADR могут быть задокументированы в самом репозитории исходного кода. Вы можете просто создавать ADR как часть репозитория Git.
Например, вы можете создать такую папку:
/doc/adr/
И добавьте к нему решения, как показано на схеме ниже.
Содержание ДОПОГ
Содержание ДОПОГ может иметь следующие разделы:
- Заголовок - заголовок записи решения.
- Решение - принятое решение. Например, используйте Elasticsearch для API поиска в масштабе предприятия.
- Статус - статус может быть предложен, принят или заменен. Если вы примете какие-либо решения и вам нужно будет изменить их позже, вы можете просто добавить новую запись с измененным статусом.
- Контекст. Каков контекст этого решения? Важно уловить полный контекст решения, чтобы читатель знал его причины.
- Последствия - в этом разделе вы можете добавить, что произойдет, если будет принято это решение. Важно перечислить все последствия, как положительные, так и отрицательные.
Весь документ должен состоять из одной-двух страниц и не более. Идея здесь в том, чтобы сделать его легким, чтобы люди могли его прочитать.
Разработчикам необходимо постоянно видеть ADR, поскольку они должны знать причины, по которым они что-то создают.
Образец ADR
Вот образец ADR, который вы можете использовать для справки.
На GitHub есть другие примеры ADR для вашей справки.
Шаблоны ADR
Это не единственный шаблон ADR, который вы можете использовать. Многие команды используют свои собственные шаблоны. Вы можете найти дополнительные коллекции шаблонов ADR на GitHub.
Заключение
По мере того, как мы все больше и больше приближаемся к Agile-разработке, нам необходимо применять подобные методы, чтобы наша архитектурная документация была более эффективной и гибкой.
Спасибо за прочтение! Если у вас есть предложения по документированию архитектурных решений, оставьте комментарий.
