Протокол архитектурного решения
Вашему вниманию предлагается перевод статьи Nolo Mokgosi – Architecture Decision Records.
congerdesign
Вы когда-нибудь оглядывались назад на то, что вы сделали, и задавались вопросом: «О чем я думал?» У меня так бывает с фотографиями подросткового возраста. Каждый раз, просматривая их, я спрашиваю себя: «Почему я выбрала эту прическу? Неужели я действительно думал, что это круто?».
Дело в том, что в то время это было круто. Мне понравилась прическа моего любимого футболиста, по этой же причине у многих детей в моей школе была такая же прическа. Поэтому, учитывая имевшуюся у меня информацию и контекст, я принял решения, которые имели смысл. Когда другие видят фотографию в мое отсутствие, они могут не понять контекст, потому что он у меня в голове.
Подводя итог, некоторые решения будут разумными, если вы понимаете контекст. Контекст КОРОЛЬ.
Введение
В мире технологий, особенно в архитектуре, решения принимаются каждый день. Эти решения принимаются на собраниях, возле кофемашин, а иногда даже за пределами офиса. Мы обсуждаем контекст решений с группами людей, но часто пренебрегаем документированием как самих решений, так и их обоснований. Несколько лет спустя мы смотрим на архитектуру и задаемся вопросом: «Почему мы спроектировали ее именно так? О чем они думали?».
В эти моменты, если нам посчастливилось иметь рядом кого-то, кто участвовал в процессе принятия решений, они могут поделиться историей, включающей ограничения, с которыми они столкнулись в то время, такие как время, стоимость и ресурсы. После этого краткого рассказа мы говорим: «О, это имеет смысл». Без кого-то, у кого есть контекст, это понимание теряется.
Чтобы решить проблему отсутствия контекста, нужно документировать наши решения. Вы можете подумать: «Еще один документ? Никто не читает документацию». Пожалуйста, дайте мне всего пять минут, чтобы объяснить, как этот подход может работать для вас и вашей организации.
Протокол архитектурного решения (ADR)
Протокол архитектурного решения (Architecture Decision Record, ADR) — это документ на определенный момент времени, в котором фиксируются архитектурные решения и их обоснование. Думайте об этом как о снимке, который говорит: «В эту дату, учитывая контекст, движущие силы и имеющуюся у нас информацию, мы приняли решение выбрать вариант Z. Мы рассмотрели варианты X, Y и Z».
Структура ADR
Согласно Майклу Найгарду в пункте № 1, ADR должно включать название, статус, контекст, решение и последствия. Кроме того, я предлагаю добавить лиц, принимающих решения и заинтересованные стороны.
Название: краткое название документа, например, «001: Решение о выборе поставщика облачных услуг для проекта данных».
Автор: укажите создателя, если wiki не фиксирует подробную информацию.
Дата: дата создания ADR.
Лицо, принимающее решение: лица, ответственные за принятие решения.
Заинтересованные стороны: те, кто высказывает рекомендации, и те, кого это решение затрагивает.
Статус: статус ADR (Черновик, Принят, Отклонен, Заменен YYY, Заменил XXX).
Контекст: в этом разделе раскрывается суть проблемы, движущие силы (функциональные и нефункциональные) и рассматриваемые варианты.
Решение: задокументируйте выбранное решение и его обоснование.
Последствия: подробно опишите результирующий контекст или состояние после реализации решения, включая компромиссы.
Как создать ADR
1. Определите необходимость ADR
Прежде чем приступить к созданию ADR, убедитесь, что решение достаточно значимое, чтобы его документировать. Подходят решения, которые оказывают долгосрочное влияние на архитектуру, выбор технологий или принципы проектирования. Как только потребность будет определена, создайте ADR со статусом «Черновик» с помощью стандартного шаблона организации или команды. ADR должен включать
- лицо, принимающее решение;
- заинтересованные стороны;
- постановку проблеме (в разделе контекста).
2. Определите проблему
Четко сформулируйте проблему или задачу, на решение которой направлено архитектурное решение. Это задает контекст для решения и помогает другим понять, почему оно принимается.
3. Опишите другие варианты
Составьте список и опишите альтернативные решения или подходы, рассматриваемые для решения проблемы. Укажите как плюсы, так и минусы каждой альтернативы. Это обеспечивает комплексное представление о процессе принятия решений.
4. Сотрудничайте
Привлекайте лиц, принимающих решения, для работы над постановкой проблемы. Обсудите все варианты и выберите выигрышные решения. Как только наступит согласие между всеми лицами, принимающими решение, привлеките к рассмотрению и утверждению решения заинтересованные стороны и экспертов (я называю это процессом продажи). Крайне важно привлекать заинтересованные стороны как можно раньше, потому что может отсутствовать контекст, который может повлиять на выбор решения.
5. Запишите решение
Как только все огни будут зелеными, измените статус на «Принят». Задокументируйте выбранное решение или подход и обоснование этого решения. Выделите причины, преимущества и компромиссы, связанные с этим решением.
6. Последствия
Опишите ожидаемые последствия решения. Сюда входят как положительные моменты, так и потенциальные недостатки. Учитывайте технические и эксплуатационные моменты а так же
влияние на бизнес.
7. Сопровождение и обновление
Если решение изменится из-за новой информации или меняющихся требований, обновите ADR, чтобы отразить текущее состояние. Измените статус текущего ADR на «Заменен YYY» и создайте новое со статусом «Заменил XXX».
Выполнив эти шаги, команды смогут создавать хорошо структурированные, информативные и ценные записи об архитектурных решениях. Эти записи будут способствовать улучшению коммуникации, обмену знаниями и принятию обоснованных решений внутри команды и во всей организации.
Пример ADR
| Название | 001: Решение о выборе облачного провайдера для проекта данных |
| Статус | Принят |
| Контекст | Наш проект предполагает разработку приложения с интенсивным использованием данных, требующего надежной и масштабируемой облачной инфраструктуры. Мы должны выбрать между Azure, AWS и GCP в качестве потенциальных поставщиков облачных услуг. Рассмотренные варианты: – Azure (Microsoft Azure): Предлагает широкий спектр услуг, тесную интеграцию с продуктами Microsoft и растущую экосистему. – AWS (Amazon Web Services): Известен своими предложениями услуг, развитой инфраструктурой и большой клиентской базой. – GCP (Google Cloud Platform): Предоставляет расширенные возможности анализа данных, услуги машинного обучения и глобальную сетевую инфраструктуру Google. Требования к качеству или нефункциональные требования, которые нами учитывались, включают производительность, масштабируемость, простоту использования, цену, интеграцию, поддержку и документацию. |
| Решение | После тщательной оценки мы выбираем Google Cloud Platform (GCP) из-за ее соответствия нашим параметрам качества и долгосрочной жизнеспособности. Обоснование: Анализ параметров качества – Производительность и масштабируемость: Глобальная сетевая инфраструктура GCP и ориентация на обработку данных хорошо согласуются с потребностями нашего приложения в масштабируемости и оперативности. – Простота использования: Удобный интерфейс GCP и интуитивно понятная навигация, вероятно, сократят кривую обучения для нашей команды, что приведет к более быстрому внедрению. – Ценообразование: Тщательный анализ затрат показывает, что структура ценообразования GCP соответствует нашему сценарию использования и обеспечивает потенциальную экономию средств за счет постоянных скидок на использование. – Интеграция: Подход открытого API GCP обеспечивает гибкость и минимизирует привязку к поставщику, что соответствует нашему стремлению к более адаптивной инфраструктуре. Долгосрочная жизнеспособность – Продолжающийся рост GCP, устоявшийся набор технологий и репутация в отрасли вселяют уверенность в ее способности поддерживать потребности нашего проекта в долгосрочной перспективе. – Наша команда инноваций создала масштабируемое и недорогое приложение на GCP. |
| Последствия | – Положительное влияние: ожидается, что надежная аналитика данных, услуги машинного обучения GCP, конкурентоспособные цены и удобный интерфейс окажут положительное влияние на разработку, производительность и общий успех нашего приложения. – Потенциальные недостатки: переход на GCP потребует целенаправленных усилий со стороны нашей технической команды для обеспечения плавной интеграции, производительности и оптимизации с услугами GCP. – Мониторинг и корректировка. Мы будем внимательно следить за производительностью нашего приложения и связанными с ним расходами на GCP. Если возникнут изменения в требованиях или непредвиденные проблемы, мы будем готовы пересмотреть наше решение. |
Преимущества ADR
| Преимущество | Описание |
| Экономия времени и затрат | Без документации решения приходится пересматривать чаще. ADR знакомит новых членов команды или организации с принятыми решениями и причинами, по которым они были приняты |
| Распределенное принятие решений | ADR помогает командам принимать обоснованные решения и более эффективно достигать консенсуса. Они позволяют любому участнику команды принимать решения или участвовать в них. При этом обеспечивается участие заинтересованных сторон |
| Прозрачность | Принятые решения не теряются в протоколах заседаний или в архивной папке на сервере документов. Сборник ADR доступен и может помочь в коммуникации |
| Обмен знаниями | ADR фиксирует и сохраняет институциональные знания, документируя идеи, компромиссы и уроки, извлеченные из прошлых решений. Поскольку лица перечислены в ADR, каждый знает к кому обратиться, в случае необходимости |
| Ответственность | Каждое решение привязано к конкретным лицам или группам, что способствует ответственности и гарантирует, что решения соответствуют целям и ограничениям команды или организации |
Заключение
Протоколы архитектурных решений (ADR) обычно используются при проектировании программном обеспечении, но их преимущества распространяются на различные архитектурные области, такие как бизнес, данные, технологии и приложения. Мы должны придавать такое же значение «документированию решений», как и созданию диаграмм и моделей, поскольку решения формируют контекст как текущих, так и будущих проектов. Очень важно понимать цель и масштаб ADR:
- ADR служат инструментом коммуникации, позволяющим командам и заинтересованным сторонам понять обоснование решений. Они действуют как инструмент отслеживания решений, помогая нам проследить, почему были приняты решения, особенно когда первоначальные движущие силы изменяются.
- ADR должны быть кратким, обычно длиной в одну или две страницы. Они должны быть читаемы в среднем в течение 5 минут и предназначены как для технической, так и для нетехнической аудитории.
- ADR являются неизменяемыми; при пересмотре решения обновите существующий статус ADR на «Заменен YYY» и создайте новую ADR.
Однако важно понимать, чем ADR не являются:
- ADR не являются долгосрочными документами (например, документом с требованиями пользователей). Они фиксируют моментальный снимок в определенный момент времени и решения должны быть достигнуты в разумные сроки.
- ADR не заменяют обсуждения и сотрудничество. Они документируют результаты обсуждений.
- ADR не ограничиваются сложными решениями. Простые решения с долгосрочным эффектом также следуетдокументировать.
Понимая эти различия, применяя ADR во всех архитектурных областях и ценя практику документирования решений, мы даем себе возможность делать осознанный выбор и создавать хорошо документированные приложения. Мы вряд ли однажды скажем: «О чем мы думали?»