Наш коллега Ефим Иванов, системный аналитик на банковских проектах, рассказал о видах спецификаций и их преимуществах. В статье вы найдёте подробное объяснение, скрины и личный опыт.
Что такое спецификация на разработку?
Спецификация — это описание разрабатываемой/разработанной части системы. Документ создают на этапе проработки задач, чтобы адаптировать требования бизнеса под системный язык и передать команде разработки.В спецификацию включают описание архитектуры, интерфейса, отдельных микросервисов, данные для тестирования, нефункциональные требования и прочее. Обычно спецификации создают системные аналитики и технические писатели, в редких случаях — продвинутые бизнес-аналитики. Как правило, её составляют на странице confluence, в swagger или в отдельном word-документе.
Кому нужна спецификация?
- Системный аналитик создаёт спецификацию, чтобы адаптировать требования бизнеса для команды разработки и описывать процесс создания системы.
- Бизнес-аналитик использует спецификацию, чтобы обозначить требования бизнеса и сравнить их с итоговом работы. А еще он исследует документы других команд, чтобы изучить готовые решения для нового или дорабатываемого процесса.
- Программистам спецификация позволяет извлечь информацию обо всей логике планируемой разработки, чтобы понять задачу: поля, запросы, форматирование и преобразования, обработку ошибок, коды систем и прочее.
- Тестировщикам спецификация позволяет определить логику работы, чтобы просчитать все возможные сценарии допущения ошибки.
- Сопровождение просит спецификацию, чтобы в случае возникновения ЧП оперативно локализовать проблему.
Сразу отмечу, что не существует идеальной документации, которая удовлетворяет требования сразу всех «стейкхолдеров». А с учетом внедрения гибких методологий, создание исчерпывающей спецификации в довольно сжатые сроки — задача не из легких.
Я выявил для себя два подхода ведения документации: один назовем «все по полочкам», а второй — «история создания решения».
Подход «все по полочкам»
Первый способ подразумевает строго повторяющейся шаблон спецификации. Например, при создании нового модуля в confluence используется шаблонный набор страниц: «Описание экранных форм», «Описание микросервисов», «Архитектура», «Интеграции», «Чек-лист внедрения» и подобные.На наших проектах это выглядело так:
Главная особенность подхода — подробное описание. Если это экранные формы, то текст содержит название компонента, его тип, источник данных, преобразование, маску, обязательность. Спецификация на микросервисы содержит сценарии вызовов, «маппинг» полей, а обработку ошибок вводят, используя макрос swagger.
Подход «все по полочкам» также позволяет описать доработку старого модуля. Достаточно открыть статьи и внести изменения. Корректировки, которые внедряют, помечают красным цветом, а после завершения работы снимают выделения.
Плюсы подхода
Описание кажется исчерпывающим. Когда знаешь, что где лежит, без проблем отслеживаешь весь путь запроса: от извлечения данных из базы до окрашивания полученного значения в интерфейсе. Подход унифицированный, что ускоряет наполнение разделов, и все участники смогут найти требуемую информацию.
Недостатки
Подход задвигает на второй план бизнес-требования к разработке. Конечно, у нас есть страница с описанием процесса и пожеланий. Однако она выглядит сильно обособлено от остальных и не гарантирует выполнение задач. Проблему решает усложнение страницы: установка якорей, добавление ссылки на задачи в Jira, дублирование части логики на страницу с требованиями.
Второй недостаток — при изменении требований проблематично отследить, когда и почему произошли перемены. Мы увидим только последние задачи.
Подход «история создания решения»
Второй способ более анархичный. Создаётся центральная страница, в которой идет «повествование», как прорабатывали и создавали решение. На первом этапе её наполняет бизнес-аналитик. Он описывает пользовательский сценарий, как часто операция выполняется, планируемую логику работы разработки, роли в приложении и прочее. После этого рисуют макет интерфейса, который прикладывают к странице.Далее в дело вступает системный аналитик. Он определяет набор микросервисов, пробегается по статье и проставляет в таблице атрибутов поля сервисов и логику форматирования. Делает ссылки на другие страницы, где добавляют подробные описания.
Задачи на разработку также добавляют в статью, чтобы понимать, в какой части сделан тот или иной функционал. Для тестировщиков в документ вносят информацию по поиску тестовых данных, которые понадобятся.
Оглавление такой страницы выглядит примерно так:
Плюсы подхода
Метод решает главную проблему «все по полочкам». Мы открываем статью и видим, как и когда решали конкретную проблему бизнеса. По опыту отмечу, подход удобен тестировщикам: он позволяет понять контекст. А еще комфортен бизнес-аналитикам: коллеги спокойны, что их требования услышаны.
Недостатки
В подходе «история создания решения» смещен фокус с разработки. Если в задаче сделать ссылку на спецификацию, программисту потребуется прочитать весь документ, чтобы понять, что от него требуется. При этом ему достаточно, чтобы конкретно написали, что важно добавить и куда. Конечно, коллеги сразу указывают пожелания в письме, но так теряется один из смыслов спецификации — постановка задачи разработчику.
Второй недостаток — в одной статье невозможно описать всю логику поведения приложения, запросы, стенды, балансировщики и прочее. Поэтому спецификация всегда будет иметь некоторую неоднозначность и неопределенность, и все детали уточняются именно при анализе кода приложения. Ну и размер статьи стремится к плюс бесконечности.
Сравнение двух подходов
Вместо вывода
Мне, как системному аналитику, больше нравится первый метод. Он позволяет быстро найти запрос. Плюс всегда знаешь, где что лежит.Если вы только выбираете подход, то продумайте, на кого вы больше ориентируетесь: бизнес или IT-команда.
