Contents

Ведение лога архитектурных решений

Видео доступно на канале

Проблема

Как принято по проектам ведется документация пользователя, а для разработчиков привычно смотреть в код.

Но по коду часто не понятно почему какое-то решение принято, а не другое.

Решение

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

Как я вижу это помогает решить следующую главную проблему:

  • Избежать одинаковых постоянных вопросов почему и что мы делаем, удобно иметь один документ по инициативе и постоянно его дополнять и делать ссылки. Так целая фича будет описана для разработчиков

Детально

Формат ADR достаточно простой и прозрачный

  • Title - кратко о чем будет ADR
  • Status [Proposed, Accepted, Deprecated, Superseded]
  • Context - Зачем мы это делаем
  • Decision - что именно будет сделано
  • Consequences - последствия

Пример шаблона

Для себя я выделил следующие случаи когда точно делать ADR

  • зависимости на новые внешние системы, хранилища, обработка, передача данных и тд
  • пересмотр решения по технологиям например по типу переход с vue на react и тд
  • механизмы взаимодействия между частами нашей системы

Ссылки