Требования от системного аналитика и шаблоны документации
При написании требований часто возникает вопрос, до какого уровня стоит детализировать требования и какие артефакты должны появится в результате системного анализа.
Я стараюсь придерживаться позиции, что это сугубо индивидуально и зависит от команды и кому как комфортно работать. Случается, что разработчикам достаточно use-case для того, чтобы сделать дизайн, а тестировщикам этого достаточно, чтобы написать тест-кейсы. Поэтому я буду писать о тех артефактах, которые могут возникнуть при написании требований и о которых надо точно задуматься к моменту завершения разработки, а вы сами решайте и договаривайтесь внутри команды, когда это стоит описывать. Однозначно только, что к концу разработки документация должна содержать все то, о чем далее пойдет речь.
Если не брать в расчет небольшие фичи, реализация которых предполагает мелкие доработки, можно достаточно просто внести изменения в имеющиеся описания. Системно можно выделить два типа задач, которые приходят в работу системному аналитику и описывать их нужно по-разному:
Задача по разработке нового сервиса или нового функционала, который лишь косвенно влияет на другие системы или компоненты
Задачи, реализация которых предполагает доработки в ряде систем по процессу (а как известно системы часто сегментированы по процессу, а бизнес-фича обычно как раз проходит по всему пайплайну и требуются доработки в ряде систем)
Для описания задач первого типа я выделила следующую структуру и блоки описания:
Общие требования
Блок, который предполагает обозначение контекста. Что это за система, для чего она служит, какие объекты содержит, какие ее границы.
— цель
Необходимо четко прописать цель системы и для чего она служит
— описание
Описание границ системы, какие задачи решает система, в общих словах описать функционал
— термины и сокращения
Перечисление в виде таблицы основные термины, сокращения и их расшифровки, если они есть в документации. Конечно, например в Confluencе есть функционал терминов, но, к сожалению, оказывается сложным внедрить эту практику всем, поэтому иногда проще этот раздел включить
— полезные ссылки
Ссылки на внешние источники, прикрепленные документы. Ссылки на внутренние документы, которые могут быть полезны.
Нефункциональные требования
Пожалуй, один из важнейших блоков и то, над чем системный аналитик должен обязательно подумать.
Наиболее важные требования, которые я выделяю и которые почти всегда следует описать, это производительности, доступность и масштабируемость. Есть масса источников, в которых подробно описано, как рассчитывать эти показатели.
Если речь идет про данные, тут следует учитывать юридические ограничения, конфиденциальность, время хранения
Используемые технологии
Опциональный блок, в котором можно перечислить языки программирования (также используемые библиотеки), интеграционную технологию, СУБД.
Сценарии использования (Use case)
Это до боли известно всем аналитикам, и я даже не буду останавливаться на этом блоке. И конечно же все сценарии использования должны присутствовать в документации и хорошо проработаны. Способ описания выбирайте на свой вкус, будь то текстовое описание или UML-диаграммы
Компонентная схема
Компонентная диаграмма из нотации UML. Позволяет понять из каких частей состоит система и какие есть взаимодействия на верхнем уровне.
На ней может быть представлено описание как конкретно данной системы, однако я предпочитаю дополнять диаграмму компонентами, с которыми данная система/сервис может взаимодействовать. Обязательно делайте пояснения текстом для диаграммы.
Модель данных
Диаграмма классов или ER-диаграмма.
Опишите основные сущности, которые предполагаются в системе. Это одна из определяющих вещей, так как почти всегда, как ни странно, границы сервисов и контекстов лежат вокруг данных. И проще всегда при проектировании систем идти как раз от данных и начать структурировать именно их. И когда решается вопрос, где разместить нужный функционал, интуитивно начинаешь думать о том, правильно ли сущности с данными разместить тут или нет.
Определите основные сущности и их атрибуты, типы, ограничения и валидации для атрибутов (это часто бывает важно). Определите взаимосвязи между сущностями.
Интеграции
— Внешние
Если необходимо интеграция с внешним провайдером данных, рисуется диаграмма последовательностей, описывается какие данные мы забираем\поставляем на уровне вызовов. Описываются все схемы сообщений, триггеры отправки, частота, особенности взаимодействия (если есть).
— Внутренние
Если сервис предоставляет данные вовне, в зависимости от способа интеграции делается либо swagger (в случае интеграции посредством передачи сообщений), либо же описываются сами структуры данных (если речь идет про шину данных), для ftp описывается структура файла и т д.
Также рисуется диаграмма последовательности для указания зависимостей визуализации взаимодействий других систем с описываемой.
Для описания задач второго типа предлагается описывать следующие разделы:
Тут несколько сложнее, поскольку, вообще говоря, нужно место, где описан общий процесс и где видно, как задача распадется на несколько систем. И далее уже описание конкретных изменений отображается в описании соответствующей системы (что вполне логично).
Описание общего процесс проще всего делать следующим образом:
Общее описание
Раздел, который предполагает обозначение контекста. Что это за функционал, какая цель и ограничения.
Пользовательский сценарий (Use-case)
Описание пользовательских сценариев для общей задачи с перечислением всех альтернатив.
Диаграмма последовательности
На ней проще всего отобразить взаимодействия систем и потоки данных для реализации. Следует разложить весь функционал по системам в разрезе данных, вызовов и триггеров. указать все взаимосвязи и зависимости задач. Далее детализировать уже на уровне каждой системы отдельно.
