Привет, на связи Ефим Иванов — Product Owner, а в недавнем прошлом системный аналитик на финтех-проектах Outlines Tech. Делюсь своим опытом, как составлял спецификации и облегчал работу команде. Я выявил два подхода: «все по полочкам» и «история создания решения». В статье найдете объяснение, чем отличаются методы, как выглядят и насколько удобны для каждого звена команды разработки.
![](https://habrastorage.org/getpro/habr/upload_files/1fd/c0c/3eb/1fdc0c3eb95732ccb6c6f10369bcf524.png)
Начну с азов: что такое спецификация на разработку?
Спецификация — это описание разрабатываемой/разработанной части системы. Документ создают на этапе проработки задач, чтобы адаптировать требования бизнеса под системный язык и передать команде разработки.
В спецификацию включают описание архитектуры, интерфейса, отдельных микросервисов, данные для тестирования, нефункциональные требования и прочее. Обычно спецификации создают системные аналитики и технические писатели, в редких случаях — продвинутые бизнес-аналитики. Составляют её на странице confluence, в swagger или в отдельном word-документе.
Кому нужна спецификация?
Системным аналитикам
Они создают спецификацию, чтобы адаптировать требования бизнеса и описывать процесс создания системы.Бизнес-аналитикам
Они использует спецификацию, чтобы обозначить требования бизнеса и сравнить их с итоговом работы. А еще они исследуют документы других команд, чтобы изучить готовые решения для нового или дорабатываемого процесса.Программистам
Разработчики извлекают из спецификации информацию обо всей логике планируемой работы, чтобы понять задачу: поля, запросы, форматирование и преобразования, обработку ошибок, коды систем и прочееQA-инженерам
Спецификация позволяет определить логику работы, чтобы просчитать все возможные сценарии допущения ошибки.Сопровождению
Они просят спецификацию, чтобы в случае возникновения ЧП оперативно локализовать проблему.
Сразу отмечу, что не существует идеальной документации, которая удовлетворяет требования сразу всех стейкхолдеров. А с учетом внедрения гибких методологий, создание исчерпывающей спецификации в довольно сжатые сроки — задача не из легких.
Я выявил для себя два подхода ведения документации: один назовем «все по полочкам», а второй — «история создания решения».
Подход «все по полочкам»
Первый способ подразумевает строго повторяющийся шаблон спецификации. Например, при создании нового модуля в confluence используется шаблонный набор страниц: «Описание экранных форм», «Описание микросервисов», «Архитектура», «Интеграции», «Чек-лист внедрения» и подобные.
На наших проектах это выглядело так:
![](https://habrastorage.org/getpro/habr/upload_files/f62/816/c70/f62816c70ca50ed2f40ca153052169c4.png)
Главная особенность подхода — подробное описание. Если это экранные формы, то текст содержит название компонента, его тип, источник данных, преобразование, маску, обязательность. Спецификация на микросервисы содержит сценарии вызовов, «маппинг» полей, а обработку ошибок вводят, используя макрос swagger.
Подход «все по полочкам» также описывает доработку старого модуля. Достаточно открыть статьи и внести изменения. Корректировки, которые внедряют, помечают красным цветом, а после завершения работы снимают выделения.
Плюсы подхода
Описание кажется исчерпывающим. Когда знаешь, что где лежит, без проблем отслеживаешь весь путь запроса: от извлечения данных из базы до окрашивания полученного значения в интерфейсе. Подход унифицированный, что ускоряет наполнение разделов, и все участники смогут найти требуемую информацию.
Недостатки
Подход задвигает на второй план бизнес-требования к разработке. Конечно, у нас есть страница с описанием процесса и пожеланий. Однако она выглядит сильно обособлено от остальных и не гарантирует выполнение задач. Проблему решает усложнение страницы: установка якорей, добавление ссылки на задачи в Jira, дублирование части логики на страницу с требованиями.
Второй недостаток — при изменении требований проблематично отследить, когда и почему произошли перемены. Мы увидим только последние задачи.
Подход «история создания решения»
Второй способ более анархичный. Создается центральная страница, в которой идет «повествование», как прорабатывали и создавали решение. На первом этапе её наполняет бизнес-аналитик. Он описывает пользовательский сценарий, планируемую логику работы разработки, как часто операция выполняется, роли в приложении и прочее. После этого рисуют макет интерфейса, который прикладывают к странице.
Далее в дело вступает системный аналитик. Он определяет набор микросервисов, пробегается по статье и проставляет в таблице атрибутов поля сервисов и логику форматирования. Делает ссылки на другие страницы, где добавляют подробные описания.
Также в статью добавляют задачи на разработку, чтобы понимать, в какой части сделан тот или иной функционал. Для тестировщиков в документ вносят информацию по поиску тестовых данных, которые понадобятся.
Оглавление такой страницы выглядит примерно так:
![](https://habrastorage.org/getpro/habr/upload_files/b86/f22/fb8/b86f22fb8e4fd108a93fadfc6f1d1093.jpg)
В итоге статья выглядит как большая история требований бизнеса с множественными вкраплениями системных вещей. Сравнить ее можно с длинным и пёстрым полотном:
![](https://habrastorage.org/getpro/habr/upload_files/cdc/be4/fc7/cdcbe4fc7c004166d39c5dfa1e3d71ff.png)
Плюсы подхода
Метод решает главную проблему «все по полочкам». Мы открываем статью и видим, как и когда решали конкретную проблему бизнеса. По опыту отмечу, подход удобен тестировщикам: он позволяет понять контекст. А еще комфортен бизнес-аналитикам: коллеги спокойны, что их требования услышаны.
Недостатки
В подходе «история создания решения» смещен фокус с разработки. Если в задаче сделать ссылку на спецификацию, программисту потребуется прочитать весь документ, чтобы понять, что от него требуется. При этом ему достаточно, чтобы конкретно написали, что важно добавить и куда. Конечно, коллеги сразу указывают пожелания в письме, но так теряется один из смыслов спецификации — постановка задачи разработчику.
Второй недостаток — в одной статье невозможно описать всю логику поведения приложения, запросы, стенды, балансировщики и прочее. Поэтому спецификация всегда будет иметь некоторую неоднозначность и неопределенность, и все детали уточняются именно при анализе кода приложения. Ну и размер статьи стремится к плюс бесконечности.
Сравнение двух подходов
«Все по полочкам» |
«История создания решения» |
|
Унификация |
Полная |
Почти нет |
Количество информации |
Расписано все |
Отсутствуют некоторые технические детали |
Связанность с бизнес-требованиями |
Минимальная, не гарантировано |
Максимальная. |
Поддержание актуальности при доработках |
Выделение цветом правок, которые внедряются. После завершения работ – снятие выделений |
Добавление ссылок на задачи, где вносятся описанные доработки |
Версионность правок |
Отсутствует (присутствует только версионность страницы confluence) |
Присутствует. Описана доработка и дана ссылка на задачу |
Удобство для системного аналитика |
Удобно: один стандарт |
Необходимо изучать весь документ и вписывать ключевые моменты |
Удобство для разработчиков |
Единый стандарт, не нужно вникать в суть задачи |
Требуется больше времени на изучение, зато происходит большее погружение в проблематику и увеличивается вероятность нахождения несостыковок в логике |
Удобство для QA-инженеров |
Есть отдельная страница, слабая связанность с конкретными атрибутами |
Обычно в статье пример ответа и ссылка на сценарий и скрипт поиска – это удобно. Плюс виден весь контекст процесса |
Удобство для сопровождения |
Неудобно все, когда ПРОД-дефект закроете? :) |
Вместо вывода
Мне, как бывшему системному аналитику, больше нравится первый метод. Он позволяет быстро найти запрос. Плюс всегда знаешь, где что лежит. Если вы только выбираете подход, то продумайте, на кого больше ориентируетесь: бизнес или IT-команда.
А если давно составляете спецификации, то расскажите, как оформляете и почему. Интересно обменяться опытом в комментариях.
Комментарии (9)
inkelyad
03.10.2023 10:29Взгляд со стороны разработчика:
Подход «история создания решения»
Кому нужна история - должны использовать разные варианты Version Control. Со всеми предлагающимися инструментами. Есть ветка 'только аналитика', есть ветки, расширяющая ее до нужных пределов для нужных целей. Когда эта ветка меняется - можно одно слить с другим. Есть инструменты 'Code Review', есть инструменты совместной работы (несколько человек над одним и тем же документом работают и потом сливают правки). Можно diff двух версий документа нормально сделать.
Ну и так далее.
Fill_Kaluga Автор
03.10.2023 10:29Что касается разработки команде обычно хватает стандартные описания микросервисов, эндпоинтов, экранных форм. С версионированием тоже проблем нет. Тут скорее тестировщики выступают с тем, что не понятно, что означают некоторые сущности, какими они бывают, и главное как их на тесте генерировать, а бегать по нескольким статьям они не хотят
avf48
03.10.2023 10:29+1А какой стандарт? Хорошо, что про спецификацию помнят))
По ГОСТу Спецификация на систему выглядит так:
ГОСТ Р 57323-2016/ISO/TS 15926-11:2015 Системы промышленной автоматизации и интеграция. Интеграция данных жизненного цикла перерабатывающих предприятий, включая нефтяные и газовые производственные предприятия. Часть 11. Методология упрощенного промышленного использования справочных данных Проблема со стейкхолдерами в том, что они на составление требований приходят с хотелками, а не документами. Требования к ИС и регл документы (возможности) описываются разными категориями работников, для разных целей... ПС может создаваться вообще не под "этого" стейкхолдера, а под похожего с точки зрения выполняемых процедур (не произв. продуктов/услуг)
ГОСТ 57195 -
Почти всё что описано в статье, можно найти в стандартах... Не нужно выбирать между структурой и ЖЦ... дак почему опять велосипед?((
Fill_Kaluga Автор
03.10.2023 10:29Основная проблема, скорее, находится в задачах, когда есть не самое "новое решение", которое начинают дорабатывать сразу несколько команд, причем с разных направлений. У них разные стандарты, по которым их работу оценивают их Лиды. Все тянут одеяло на себя. А если еще и исходная команда распалась, то совсем беда. Мы участвовали в нескольких проектах под условных названием "Единое окно", когда делают приложение, в которое "встраивается" всё, что было сделано до этого. и на таких проектах приходится изобретать велосипед и даже колесо)
tik4
03.10.2023 10:29Все это конечно зависит от требуемых темпов разработки и исходного состояния проекта. Если надо бежать быстрее паровоза, чтобы занять нишу, то хватает наскальных рисунков где угодно. Ещё бывает легаси вообще без спек, которое надо незначительно доработать и забыть на 100500 лет, там проще описать конкретную доработку.
А вот если проект долгосрочный и делается без подгорания в одном месте, то выгодней его нормально расписать и потом своевременно дополнять требованиями.
Касаемо версионности правок - мы обычно ведём как версии документа в виде отдельных страниц в конфе, так и ревизии изменений внутри каждой страницы с подробным описанием изменений и раскраской всеми цветами радуги, ссылками на макеты и прочим блэкджеком.
И отделяем архитектуру, описания api, тесткейсы, общие и техописания в отдельные от требований документы. Соответственно ведут их разные люди - архитекторы свое, аналитики свое, техписы и разрабы свое. Хотя где-то аналитик может быть как Дартаньян - один за всех)Fill_Kaluga Автор
03.10.2023 10:29У нас все так же прям один в один. Как и у многих. Новый проект, новая команда, все ведут «все по ГОСТу», разрисовывают, расписывают. Как раз для решения проблем на стыке легаси и кросспроектных задач появилась у нас такая альтернатива
Batalmv
Идеальная картина:
Спеки пишутся по первому методу, так как они могут быть ПОСЛЕ разработки как справочник. Часто после разработки, либо паралельно с ней. Либо не пишутся, если заказчик не оплатил :) Иначе это не спека
Разработка идет по описанию задач для разработки, где собственно описывается то, что надо сделать здесь и сейчас. Как именно - зависит от методологии организации, команды, главное чтобы в моменте было понятно, что делать
В таком картине мире, не страдает ни то, ни другое. Но естественно надо платить чуток поболее.
Есть опыт использования первого подхода, когда бралась актуальная версия спеки, вносились изменения в режиме track changes. Разработчик получал задачу реализовать изменения с версии 1.42 до версии 1.44. Дополнительно в задаче могло описываться что-то, что важно здесь и сейчас. Получалось на самом деле не сильно сложнее, просто требовалось время научить всех прыгать по изменениям в документе. Но это больше работает в "большом" Enterprise, так как там часто и контракты такие, что надо иметь большую и качественную бумажку прикрыть свою пятую точку.
Как архитектор, я свою часть всегда пишу отдельно, так как имею много чего сказать, да и обычно, если я есть, значит есть много нефункциональных требований и интеграций, которые надо реализовать. А значит надо иметь отдельный документ, где показана в разных разрезах ИТ-картина решения
Второй подход не испрользовал именно в таком виде, так как такая идеология работает, на мой взгляд, в виде задачек в Jira. Просто так проще и понятнее. Задачки сами по себе самодостаточны, функционал системы позволяет их легко группировать, делить на релизы, ставить связи и вообще - управлять процессом. Как отдельный документ - не, скорее всего предложу выкинуть и забыть как страшный сон
Fill_Kaluga Автор
Спасибо за комментарий! На самом деле второй подход я встретил только на последнем проекте. Сначала он казался абсурдным, но он показал свою жизнеспособность, так как: 1) часто приходилось дорабатывать решения других команд 2) многие решения являются устаревшими, не имеют спецификаций 3) Только происходит "переходный процесс" унификации всех направлений, при этом все равно все проекты в большей части живут своей жизнью (хотя общий технический стек). В таких реалиях приходится много вопросов отдавать на откуп разработчику и и ему приходится вникать в задачу. В новых решениях, конечно, однозначно первый вариант