С ростом системы растет и объем документации. Как подготовить такое описание архитектуры, чтобы все заинтересованные смогли легко найти интересующую информацию? Ниже описана простая практика составления списка хитов в хитпараде артефактов.
Выгоды от использования
- Явно выделяет наиболее важные архитектурные артефакты
- Представляет архитектурные артефакты в контексте системы в целом
- Создает целостное и легковесное архитектурное описание всей системы
Описание
Обычно «Хит-парад архитектурных артефактов» — это простая wiki-страница со ссылками. Каждая ссылка содержит:
Заголовок — краткое и понятное описание артефакта. Например — название документа или диаграммы.
Описание — говорит о том, почему этот артефакт важен или интересен. Отвечает на вопрос: «Что заинтересованные стороны получат от ознакомления с этим артефактом?». Может содержать дату создания или последнего обновления артефакта.
Предостережения — артефакты могут быть не полными или устаревшими. Предостережения указывают на то, что в настоящий момент информацию, полученную из артефакта следует использовать с осторожностью.
Процесс создания хит-парада
- Расположите артефакты вокруг потребностей заинтересованных сторон. Артефакты, закрывающие одни и те же потребности, разместите вместе. Дайте название каждой из получившихся групп. Например: разграничение прав доступа, методы обеспечения безопасности, масштабирование при росте числа клиентов, аудит по требованию регулятора.
- Одни и те же артефакты могут закрывать различные потребности. Укажите это явно в «Описании» и «Предостережениях». Это нужно для того, чтобы при ознакомлении не были упущены важные детали, расположенные в неочевидных местах.
- Подумайте об использовании официальной документации на используемые фреймворки. Если вы используете Vault или Spring Boot — можете смело поставить ссылки на оф. описания.
Пример
Другие ссылки по теме «Описание архитектуры»
Об архитектуре для разработчиков (by Simon Brown)
Эффективные способы описания архитектуры
