Отношение к артефактам
Есть разные способы организации работы команды: всё зависит от подхода — заказная или проектная разработка, от величины компании и самой команды, от принятой методологии. От этого прямо зависит и отношение инженеров к документации. В классическом варианте работы по скраму разработчик будет доверять написанному в задаче, поскольку она, как правило, содержит уже четкую выжимку и ожидаемый результат работы. Но она не дает полного представления о целевом решении — это могут быть отдельные фичи без привязки к глобальному проекту. В лучшем случае тикет будет содержать ссылки на общую спецификацию. В заказной разработке документация вообще бывает очень скудной (опять же, всё зависит от компании), ограничиваясь описанными требованиями.
Многие разработчики — в силу привычки или потому что так исторически сложилось — работают, основываясь на том, что описано в задачке, или ориентируются на сформулированные функциональные требования или на дизайн-макет. О существовании диаграмм, схем и прочих «картинок» они могут даже не знать.
Так может сложиться по нескольким причинам:
- Отсутствие структуры документации — хаотично разбросанные требования. Разработчик элементарно может не знать, где лежит та или иная диаграмма, и не тратит время на поиск того, чего, возможно, нет.
- Схемы могут быть, но сделаны не по нотации или содержаться в неактуальном состоянии.
- Разработчик знает о существовании диаграмм и даже где в документации они лежат, но не пользуется, так как не разбирается в нотации.
Давайте рассмотрим, какие из артефактов и инструментов в работе аналитика могут быть реально полезны для разработчика.
UML-диаграммы и BPMN: не просто красивые ромбики
UML (Unified Modeling Language) — унифицированный язык моделирования — графический язык, который с помощью диаграмм и схем описывает разнообразные процессы и структуры.
BPMN (Business Process Model and Notation) — диаграмма, отражающая бизнес-процесс, на первый взгляд выглядит как схема электропроводки, но при грамотном составлении в ней хранятся ответы на многие вопросы, а также содержится целевая картина работы приложения.
Любые UML-диаграммы или BPMN действительно могут быть полезными разработчику только при выполнении следующих условий: если они не противоречат документации и актуальны. Нет никакого смысла в красивой схеме, если она не соответствует текущей реализации или описывает устаревший процесс. Тогда это не помощь, а источник новых багов.
Реальная ценность диаграммы в том, что с помощью нее можно проиллюстрировать процесс, сделать сложные описания ветвлений и множественных условий визуальными. Сравните для примера:
А вот BPMN-диаграмма, иллюстрирующая этот процесс:
Для облегчения восприятия здесь сознательно опущены подпроцессы и пулы — сторонние системы, в которые ходят запросы. Основной посыл в том, что и текст, и схема передают одну и ту же логику, но на диаграмме сразу наглядно видно, где происходят развилки, какие есть условия, где можно ошибиться. Именно это делает BPMN и UML полезными для разработчика: они позволяют увидеть процесс целиком, а не разрозненные фразы в тикетах или техническом задании.
Чаще всего к диаграммам обращаются бэкендеры: им важно видеть, как сервисы общаются между собой, где проходят интеграции и как запрос путешествует по цепочке. Фронтендерам схемы тоже могут сильно упростить жизнь, особенно когда речь идет о сложных формах с множеством шагов и развилок: на диаграмме (хорошо сделанной) сразу видно, что будет, если пользователь закроет окно на середине пути, введет неверные данные или захочет вернуться назад.
Диаграммы полезны не только разработчикам. Тестировщики могут использовать их как готовую карту для составления тест-кейсов: проще убедиться, что проверены все ветки сценария. Продакт-менеджерам такие схемы помогают наглядно объяснять фичу бизнесу и согласовывать процессы. А дизайнерам — понять, в каких точках интерфейс должен реагировать иначе, где нужна дополнительная подсказка или ошибка.
Sequence Diagram: интеграционное взаимодействие
Sequence Diagram — это еще один из типов диаграмм в языке моделирования UML. Ранее мы уже рассказывали, как создавать sequence-диаграммы с помощью PlantUML и почему базовый скил аналитиков может пригодиться не только им. С помощью сиквенсов можно разобраться, наглядно посмотреть на процессы интеграционного взаимодействия, понять, куда ходит запрос, выявить подпроцессы или дополнительные шаги.
На что стоит обратить внимание в сиквенсах разработчику:
- Места, где идет цепочка вызовов без ретраев, — потенциальные точки падения.
- Асинхронные ответы — значит, нужно думать о статусе ожидания на фронте.
Подводные камни, которые могут быть видны сразу только на диаграмме, без необходимости вчитывания в большие объемы текста:
- Ретраи и идемпотентность.
- Таймауты.
- Кеш и консистентность.
- «Гонка» состояний UI — это когда несколько событий пытается одновременно изменить состояние интерфейса, и результат зависит от того, какое из них сработает раньше.
- Возможные деградации системы.
ERD-диаграммы и очень удобный инструмент для их создания
dbdiagram: быстрый способ визуализировать структуру базы без боли
Обычно ERD-диаграммы (Entity Relationship Diagram) создают, чтобы показать связи между таблицами в базе данных. По-хорошему они должны быть в каждой системе, где больше трех таблиц, но на практике их либо нет, либо они лежат где-то в PDF от 2021 года и не соответствуют реальности.
Вот тут и может помочь dbdiagram.io — достаточно простой в освоении и интуитивный онлайн-сервис, который позволяет строить ERD прямо из текстового описания.
Например:
```
Table orders {
id int [pk]
user_id int [ref: > users.id]
status varchar
created_at timestamp
}
Table users {
id int [pk]
name varchar
email varchar
}
```
Сервис мгновенно рисует схему: стрелочки, связи, ключи, всё аккуратно и наглядно. Сами таблички можно двигать, как удобно.
Чем это удобно разработчику:
Во-первых, сервис позволяет описывать схему в виде кода, пишем в понятном текстовом синтаксисе, а на выходе получаем ERD с таблицами, связями и типами полей. Не нужно вручную тащить квадратики мышкой, как в draw.io, например.
Во-вторых, dbdiagram умеет конвертировать схему в DDL-код для популярных СУБД (PostgreSQL, MySQL, SQL Server, SQLite). То есть можно буквально за минуту превратить описание в рабочий SQL-скрипт для создания таблиц. Это удобно, когда нужно:
- быстро поднять базу локально, чтобы проверить гипотезу;
- обсудить структуру или показать команде, как связаны доменные сущности.
Еще удобный момент — импорт из существующей базы. Можно выгрузить DDL, вставить в dbdiagram и получить схему визуально. Отличный способ разобраться в старом проекте или проверить, где нарушены связи.
Сервис dbdiagram также поддерживает совместное редактирование: можно делиться ссылкой с коллегами, править схему вместе, комментировать таблицы, фиксировать версии. Для больших проектов с десятками таблиц это становится спасением: схема всегда под рукой, в актуальном виде, никаких старых картинок, которые нужно перерисовывать с нуля.
Советы по работе с документацией и управлением требованиями
Совет по работе с документацией номер один: читать документацию.
Кроме шуток, иногда разработчики ленятся читать спецификации, фронтендеры пользуются только макетом, а баги чинят уже по факту.
А если серьезно, есть некоторые лайфхаки для более удобной работы с документацией.
Естественно, делать закладки и ссылки-якоря на наиболее часто используемые разделы.
Например, в Вики:
Комментарии можно оставлять прямо во время чтения документации — так они не затеряются в переписке, а еще удобно через какое-то время при переключении контекстов вернуться и освежить в памяти предысторию вопроса, понять, почему выбрано именно то или иное решение. Это может сильно помочь при онбординге нового сотрудника в проект.
История изменений применяется практически везде. Можно предложить ввести такую практику, если в команде не применяется: удобно отслеживать версионность и изменения.
Очень удобный лайфхак — подписка на изменения. В разных фреймворках это реализуется по-разному.
В Confluence есть возможность отслеживать изменения через Watch page / Watch space.
В письме или уведомлении внутри Confluence приходит список изменений и ссылка на diff.
Кроме того, можно фильтровать по авторам изменений.
В Вики это реализовано менее удобно, однако можно подписаться на страницу или раздел: в уведомлениях приходит история изменений, но нет такой наглядной ленты, как в Confluence, — чаще просто список, что изменилось, с выделением абзацев. Историю можно посмотреть вручную в «История изменений» и сравнить две версии, но из неудобного — не подсвечивается, что именно было изменено.
В Notion есть Version history с визуальным сравнением версий. Можно включить уведомления об изменениях в документе.
В Google Docs есть уведомления о комментариях и «История версий». Можно подписаться на комментарии или периодически смотреть через вкладку Version history.
Самый продвинутый уровень — если документация в команде ведется в GitHub / GitLab Wiki. История изменений хранится как коммиты. Можно подписаться на репозиторий, чтобы получать diff изменений в wiki-страницах.
Miro — не просто рисовалка
Для многих разработчиков Miro — это место, где аналитики и дизайнеры рисуют что-то цветное, а они туда заглядывают только на демо или презентациях.
У меня есть собственное правило, которым я пользуюсь много лет: в любой непонятной ситуации я рисую, раскладываю на простейшие схемы, стрелочки и квадратики, даже самой себе, а показать кому-то так проще всего. Именно они помогают не только понять, но и объяснить — доходчиво.
Плюс ко всему у Miro очень приятный визуальный и простой интерфейс.
Miro можно использовать для архитектурных сессий: рисовать модули, связи, события. А еще можно мгновенно фиксировать идеи при обсуждении. Держать версию архитектуры «как есть» и «как будет» прямо на доске.
Вместо заключения
Можно смело сказать, что артефакты аналитика — это не просто формальность для отчетности, а рабочий инструмент, который реально экономит время и снижает количество возможных багов. Диаграммы помогают увидеть полную картину, критерии приемки — выявить альтернативные сценарии еще до тестирования, а инструменты вроде Jira, Confluence и Miro — синхронизировать команду и держать проект под контролем.
Чтение документации, умение быстро находить в ней нужное и привычка проверять взаимосвязи между задачами — это не «прихоть», а такой же навык разработчика, как умение писать чистый код. Те, кто освоил этот подход, тратят меньше времени на переделки, реже ловят критические баги и проще договариваются с аналитиками.
А значит, если хотите работать быстро, качественно и без сюрпризов на проде, начните с простого: откройте документацию и загляните в артефакты, которые сделал аналитик, — уверена, там уже есть ответы на вопросы, которые у вас даже не успели появиться.
