Architecture Decision Record

Active theme: Light

← документы

Советы по написанию хороших ADR

Характеристики хорошей ADR:

  • Обоснование: объясните причины принятия конкретного AD. Сюда может входить контекст (см. ниже), плюсы и минусы различных возможных вариантов, сравнение функций, обсуждение затрат и выгод и многое другое.

  • Конкретность: каждая ADR должна касаться одного AD, а не нескольких.

  • Метки времени: указывайте, когда был написан каждый пункт ADR. Это особенно важно для аспектов, которые могут меняться со временем, таких как затраты, графики, масштабирование и т. п.

  • Неизменяемость: не изменяйте существующую информацию в ADR. Вместо этого дополняйте ADR, добавляя новую информацию, или заменяйте ADR, создавая новую ADR.

Характеристики хорошего раздела «Контекст» в ADR:

  • Объясните ситуацию вашей организации и деловые приоритеты.

  • Включите обоснования и соображения, основанные на социальном составе и навыках ваших команд.

  • Включите уместные плюсы и минусы и опишите их в терминах, соответствующих вашим потребностям и целям.

Характеристики хорошего раздела «Последствия» в ADR:

  • Объясните, что следует из принятия решения. Сюда могут входить эффекты, исходы, результаты, дальнейшие действия и многое другое.

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

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

Новая ADR может заменить предыдущую ADR:

  • Когда принимается AD, заменяющий или делающий недействительной предыдущую ADR, следует создать новую ADR