как оформить спецификацию, чтобы не запутаться самому и не выбесить коллег / Хабр | Веб-студия Nat.od.ua

Привет, на связи Ефим Иванов — Product Owner, а в недавнем прошлом системный аналитик на финтех-проектах Outlines Tech. Делюсь своим опытом, как составлял спецификации и облегчал работу команде. Я выявил два подхода: «все по полочкам» и «история создания решения». В статье найдете объяснение, чем отличаются методы, как выглядят и насколько удобны для каждого звена команды разработки. 

Начну с азов: что такое спецификация на разработку?

Спецификация — это описание разрабатываемой/разработанной части системы. Документ создают на этапе проработки задач, чтобы адаптировать требования бизнеса под системный язык и передать команде разработки.

В спецификацию включают описание архитектуры, интерфейса, отдельных микросервисов, данные для тестирования, нефункциональные требования и прочее. Обычно спецификации создают системные аналитики и технические писатели, в редких случаях — продвинутые бизнес-аналитики. Составляют её на странице confluence, в swagger или в отдельном word-документе.

Кому нужна спецификация?

• Системным аналитикам
  Они создают спецификацию, чтобы адаптировать требования бизнеса и описывать процесс создания системы.

• Бизнес-аналитикам
  Они использует спецификацию, чтобы обозначить требования бизнеса и сравнить их с итоговом работы. А еще они исследуют документы других команд, чтобы изучить готовые решения для нового или дорабатываемого процесса.

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

• QA-инженерам
  Спецификация позволяет определить логику работы, чтобы просчитать все возможные сценарии допущения ошибки.

• Сопровождению
  Они просят спецификацию, чтобы в случае возникновения ЧП оперативно локализовать проблему.

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

Я выявил для себя два подхода ведения документации: один назовем «все по полочкам», а второй — «история создания решения».

Подход «все по полочкам»

Первый способ подразумевает строго повторяющейся шаблон спецификации. Например, при создании нового модуля в confluence используется шаблонный набор страниц: «Описание экранных форм», «Описание микросервисов», «Архитектура», «Интеграции», «Чек-лист внедрения» и подобные.

На наших проектах это выглядело так:

Главная особенность подхода — подробное описание. Если это экранные формы, то текст содержит название компонента, его тип, источник данных, преобразование, маску, обязательность. Спецификация на микросервисы содержит сценарии вызовов, «маппинг» полей, а обработку ошибок вводят, используя макрос swagger.

Подход «все по полочкам» также описывает доработку старого модуля. Достаточно открыть статьи и внести изменения. Корректировки, которые внедряют, помечают красным цветом, а после завершения работы снимают выделения.

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

Недостатки
Подход задвигает на второй план бизнес-требования к разработке. Конечно, у нас есть страница с описанием процесса и пожеланий. Однако она выглядит сильно обособлено от остальных и не гарантирует выполнение задач. Проблему решает усложнение страницы: установка якорей, добавление ссылки на задачи в Jira, дублирование части логики на страницу с требованиями.

Второй недостаток — при изменении требований проблематично отследить, когда и почему произошли перемены. Мы увидим только последние задачи.

Подход «история создания решения»

Второй способ более анархичный. Создается центральная страница, в которой идет «повествование», как прорабатывали и создавали решение. На первом этапе её наполняет бизнес-аналитик. Он описывает пользовательский сценарий, планируемую логику работы разработки, как часто операция выполняется, роли в приложении и прочее. После этого рисуют макет интерфейса, который прикладывают к странице.

Далее в дело вступает системный аналитик. Он определяет набор микросервисов, пробегается по статье и проставляет в таблице атрибутов поля сервисов и логику форматирования. Делает ссылки на другие страницы, где добавляют подробные описания.

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

Оглавление такой страницы выглядит примерно так:

В итоге статья выглядит как большая история требований бизнеса с множественными вкраплениями системных вещей. Сравнить ее можно с длинным и пёстрым полотном:

Плюсы подхода
Метод решает главную проблему «все по полочкам». Мы открываем статью и видим, как и когда решали конкретную проблему бизнеса. По опыту отмечу, подход удобен тестировщикам: он позволяет понять контекст. А еще комфортен бизнес-аналитикам: коллеги спокойны, что их требования услышаны.

Недостатки
В подходе «история создания решения» смещен фокус с разработки. Если в задаче сделать ссылку на спецификацию, программисту потребуется прочитать весь документ, чтобы понять, что от него требуется. При этом ему достаточно, чтобы конкретно написали, что важно добавить и куда. Конечно, коллеги сразу указывают пожелания в письме, но так теряется один из смыслов спецификации — постановка задачи разработчику.

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

Сравнение двух подходов

Вместо вывода

Мне, как бывшему системному аналитику, больше нравится первый метод. Он позволяет быстро найти запрос. Плюс всегда знаешь, где что лежит. Если вы только выбираете подход, то продумайте, на кого больше ориентируетесь: бизнес или IT-команда.

А если давно составляете спецификации, то расскажите, как оформляете и почему. Интересно обменяться опытом в комментариях.