Как выбрать диаграмму: процесс, поведение или архитектура
Практический материал для аналитика и тимлида: как выбрать схему по рабочему вопросу, не смешивать процесс, взаимодействия, состояния, границы системы и данные в одном рисунке.
Когда использовать
Материал нужен, когда команда уже понимает тему разговора, но не понимает, какой схемой сделать ее общей:
- показать границу системы и внешних участников;
- разобрать порядок вызовов и ответственность;
- проверить состояния объекта и допустимые переходы;
- описать рабочий процесс с развилками;
- договориться о сущностях и связях данных;
- подготовить один сценарий к разработке или приемке.
Цель диаграммы - не подтвердить знание нотации. Она должна помочь участникам увидеть один и тот же вопрос, найти разрыв и принять следующий шаг.
Сначала назвать рабочий вопрос
Плохая постановка:
Нарисовать архитектуру фичи.
В ней непонятно, что именно должно стать яснее: состав систем, порядок взаимодействий, жизненный цикл заявки, структура данных или процесс работы оператора.
Рабочая постановка звучит конкретнее:
- где проходит граница нашей ответственности;
- кто первым вызывает внешний контур;
- что происходит после таймаута;
- из каких состояний заявку можно отменить;
- где данные появляются и кто считает их источником истины;
- на каком шаге оператор подключается к автоматическому процессу.
Если вопрос нельзя сформулировать одним предложением, одной диаграммы, скорее всего, будет недостаточно.
Карта выбора
Пройдите вопросы сверху вниз:
- Нужна граница системы и внешних участников - начните с контекстной схемы.
- Важен порядок взаимодействий - используйте sequence-диаграмму.
- Важен жизненный цикл объекта - используйте state diagram и таблицу переходов.
- Нужен рабочий поток людей и систем - используйте BPMN или компактный flowchart.
- Нужны сущности и связи данных - используйте концептуальную модель или ER-диаграмму.
Эта последовательность не выбирает инструмент за команду. Она удерживает разговор от типичной ошибки: пытаться одним рисунком одновременно показать архитектуру, бизнес-процесс, API-вызовы, статусы и таблицы базы.
Какой тип схемы отвечает на какой вопрос
| Рабочий вопрос | Подходящий вид | Что должно быть видно | Что лучше вынести отдельно |
|---|---|---|---|
| Где система начинается и заканчивается? | Контекстная схема, C4 Context или простая карта систем | Пользователи, системы, внешние контуры, ответственность | Внутренние классы, все API-методы, детальные статусы |
| Кто с кем и в каком порядке взаимодействует? | Sequence-диаграмма | Участники, сообщения, ответы, ошибки, ветки, следующий владелец | Полный бизнес-процесс и устройство баз данных |
| Как меняется объект или операция? | State diagram и таблица переходов | Состояния, события, условия, финальность, запрещенные переходы | Детали транспорта и расположение компонентов |
| Как работа проходит через людей и системы? | BPMN или компактный flowchart | Шаги, роли, развилки, ожидания, ручные действия | Полный контракт API и физическая модель данных |
| Какие сущности существуют и как связаны? | Концептуальная модель или ER-диаграмма | Сущности, ключевые связи, обязательность, кардинальность | Экранные формы и порядок сетевых вызовов |
| Из каких крупных частей состоит решение? | C4 Container/Component или упрощенная компонентная схема | Крупные компоненты, назначение и зависимости | Классы, методы и весь deployment-контур без необходимости |
Название нотации вторично. Если простая схема с понятной легендой отвечает на вопрос лучше формально правильной, но перегруженной диаграммы, для рабочего обсуждения полезнее простая схема.
Шаг 1. Определить читателя и решение
Одна и та же тема требует разной глубины:
- бизнесу важно увидеть границу процесса и ожидаемый результат;
- аналитику - сценарий, данные, состояния и открытые вопросы;
- разработчику - контракты, зависимости и ответственность компонентов;
- QA - ветки, условия, ошибки и проверяемые результаты;
- поддержке - наблюдаемые статусы, идентификаторы и ручные действия;
- безопасности - границы доверия, чувствительные данные и точки контроля.
Перед схемой заполните две строки:
После просмотра читатель должен понять:
После обсуждения команда должна решить:Если вторая строка остается пустой, схема рискует стать иллюстрацией без рабочего результата.
Шаг 2. Выбрать один уровень масштаба
Полезно заранее назвать масштаб:
| Масштаб | Пример вопроса |
|---|---|
| Контекст | Какие системы и роли участвуют в проверке заявки? |
| Один сценарий | Что происходит от отправки до финального результата? |
| Один объект | Какие состояния имеет заявка и кто их меняет? |
| Один контракт | Какие запросы, ответы и ошибки проходят через API? |
| Один участок процесса | Как оператор разбирает запрос после автоматической ошибки? |
Не стоит на контекстной схеме одновременно раскрывать поля запроса, внутренние таблицы и все варианты retry. Контекст дает карту. Детали появляются на следующей схеме или в таблице рядом.
Шаг 3. Сначала сделать черновик смыслов
До выбора Mermaid, Miro, PlantUML или другого инструмента выпишите:
- участников и границы ответственности;
- входное событие;
- основной результат;
- один-два важных альтернативных исхода;
- данные или состояния, без которых поведение непонятно;
- открытые вопросы;
- то, что намеренно не входит в схему.
Этот черновик быстрее показывает пробелы, чем попытка сразу выровнять блоки и стрелки.
Шаг 4. Проверить, не нужны ли две маленькие схемы
Разделяйте схемы, если одновременно приходится объяснять:
- карту систем и порядок запросов;
- бизнес-процесс и технические ошибки;
- состояния объекта и внутреннее устройство сервисов;
- логическую модель данных и физические таблицы;
- основной сценарий и редкие эксплуатационные ветки.
Например:
- Контекстная схема показывает пользователя, продукт, интеграционный контур и внешнюю систему.
- Sequence-диаграмма раскрывает один критичный сценарий.
- Таблица переходов фиксирует, что происходит с операцией после каждого ответа.
Три небольших артефакта легче обсуждать и поддерживать, чем одну схему со всеми деталями.
Шаг 5. Поставить диаграмме проверяемый вопрос
Хороший review диаграммы - это не “всем ли нравится”, а попытка найти неоднозначность:
- где находится источник истины;
- кто инициирует действие;
- кто отвечает после ошибки;
- какой ответ считается финальным;
- что происходит при таймауте;
- можно ли повторить действие;
- какое состояние увидит пользователь;
- где подключается поддержка;
- какие данные нельзя показывать или логировать;
- какая граница пока остается гипотезой.
Если схема не помогает ответить на вопрос, добавлять еще блоки необязательно. Возможно, выбран не тот вид артефакта.
Типичные ошибки выбора
Flowchart вместо модели состояний
Flowchart удобно показывает порядок действий. Но если главный вопрос - какие состояния допустимы и что переводит объект между ними, нужны state diagram и таблица переходов. Иначе статус смешивается с шагом процесса.
Sequence вместо полного процесса
Sequence-диаграмма хорошо показывает обмен между участниками в одном сценарии. Она становится неудобной, когда в нее пытаются поместить все роли, ручные регламенты, дни ожидания и десятки бизнес-развилок.
C4 вместо карты ответственности
C4 помогает говорить о программных системах и контейнерах. Но если проблема в том, кто принимает решение, проверяет данные или действует после сбоя, одной архитектурной схемы недостаточно. Нужны роли, процесс или таблица ответственности.
ER-диаграмма вместо бизнес-языка
Физические таблицы не заменяют разговор о сущностях предметной области. Сначала полезно договориться, что такое заявка, операция, участник и результат, а уже потом обсуждать хранение.
Короткий бриф на диаграмму
Рабочий вопрос:
Читатели:
Решение после обсуждения:
Тип схемы:
Масштаб:
Что обязательно показать:
- ...
Что намеренно не показываем:
- ...
Открытые вопросы:
- ...
Связанные артефакты:
- контракт;
- таблица переходов;
- критерии приемки;
- запись решения.Чеклист перед публикацией или встречей
- у диаграммы есть один рабочий вопрос;
- выбранный вид соответствует этому вопросу;
- понятны читатель и требуемое решение;
- схема держит один уровень масштаба;
- роли, системы и состояния не смешаны без необходимости;
- у стрелок и переходов есть понятный смысл;
- текст читается без обязательного zoom;
- обозначения объяснены рядом;
- открытые вопросы не выглядят как подтвержденные факты;
- чувствительные данные, внутренние адреса и идентификаторы удалены;
- рядом есть следующий артефакт: контракт, таблица, критерии или решение.
Куда идти дальше
- Если непонятна граница системы, начните с рабочей карты системы.
- Если важен порядок взаимодействий, соберите sequence-диаграмму одного сценария.
- Если важен жизненный цикл объекта, зафиксируйте состояния и переходы.
Диаграмма полезна не количеством элементов. Ее качество определяется тем, помогла ли она увидеть разрыв, договориться о смысле и сделать следующий шаг проверяемым.