Описание архитектуры системы: «хит-парад архитектурных артефактов»

С ростом системы растет и объем документации. Как подготовить такое описание архитектуры, чтобы все заинтересованные смогли легко найти интересующую информацию? Ниже описана простая практика составления списка хитов в хитпараде артефактов.

Выгоды от использования

  • Явно выделяет наиболее важные архитектурные артефакты
  • Представляет архитектурные артефакты в контексте системы в целом
  • Создает целостное и легковесное архитектурное описание всей системы

Описание

Обычно «Хит-парад архитектурных артефактов» — это простая wiki-страница со ссылками. Каждая ссылка содержит:

Заголовок — краткое и понятное описание артефакта. Например — название документа или диаграммы. 

Описание — говорит о том, почему этот артефакт важен или интересен. Отвечает на вопрос: «Что заинтересованные стороны получат от ознакомления с этим артефактом?». Может содержать дату создания или последнего обновления артефакта. 

Предостережения — артефакты могут быть не полными или устаревшими. Предостережения указывают на то, что в настоящий момент информацию, полученную из артефакта следует использовать с осторожностью.

Процесс создания хит-парада

  • Расположите артефакты вокруг потребностей заинтересованных сторон. Артефакты, закрывающие одни и те же потребности, разместите вместе. Дайте название каждой из получившихся групп. Например: разграничение прав доступа, методы обеспечения безопасности, масштабирование при росте числа клиентов, аудит по требованию регулятора.
  • Одни и те же артефакты могут закрывать различные потребности. Укажите это явно в «Описании» и «Предостережениях». Это нужно для того, чтобы при ознакомлении не были упущены важные детали, расположенные в неочевидных местах.
  • Подумайте об использовании официальной документации на используемые фреймворки. Если вы используете Vault или Spring Boot – можете смело поставить ссылки на оф. описания.

Пример

Описание архитектуры системы: «хит-парад архитектурных артефактов»
Описание архитектуры системы: «хит-парад архитектурных артефактов»
Другие ссылки по теме «Описание архитектуры»

Об архитектуре для разработчиков (by Simon Brown)

Эффективные способы описания архитектуры

Метафора системы и архитектура

Создание компонентной структуры продукта

Share

Leave a Reply