Введение
Для компании SimpleOne управление спецификациями требований было настоящей головной болью, требующей унификации подходов и учета потребностей разных команд. Мы стояли перед выбором: сделать свое решение для управления требованиями и сбора спецификаций или попробовать уже существующие практики. Концепция DocOps привлекла внимание тем, что помогает стандартизировать инструменты и навести порядок в хранении артефактов... В этой статье мы расскажем, как внедрили подход на основе docs as code, какие преимущества получили и какие трудности преодолели на пути.
О компании
SimpleOne — российский разработчик решений для автоматизации бизнес-процессов на базе собственной low-code платформы. Платформа помогает автоматизировать работу IT, HR, АХО и других подразделений компании, основываясь на лучших практиках предоставления сервисов (ITIL, VeriSM). Наши решения ориентированы на корпоративных и государственных клиентов, стремящихся к повышению эффективности и цифровой трансформации бизнеса.
Об авторах
Дарья Васьковская — аналитик в SimpleOne, экс-Яндекс. Участвую в запуске новых продуктов и объединяю опыт из разных сфер для поиска лучших решений
Сергей Бакин — руководитель направления бизнес-системного анализа SimpleOne, CBAP, более 12 лет опыта в IT.
Предыстория
До внедрения Doc as Code мы управляли требованиями через Google Docs, создавая спецификации для элементов бэклога, которые затем попадали в очередь задач продуктовых команд.. Это приводило к проблемам:
Отсутствие версионирования: Трудно было отслеживать изменения и возвращаться к предыдущим версиям спецификаций.
Трудности в совместной работе: Было трудно сообщать о конкретных изменениях в спецификации с течением времени. Процесс ревью спецификаций был муторным и синхронным.
Мы решили провести эксперимент и создать свой подход — Spec‑as‑Code. Этот подход вырос из идеи Docs-as-Code, которая активно используется техническими писателями из таких компаний как Google, Microsoft,Twitter, Т-Банк, Ozon и другими для управления документацией как кодом.
Преимущества Spec-as-Code: почему вам стоит задуматься об этом подходе
Версионирование:
Возможность отслеживать изменения и возвращаться к предыдущим версиям спецификаций. Например, если в новой версии спецификации оказалось ошибочное требование, мы можем быстро вернуться к предыдущей версии без потерь.
Прозрачность и контроль:
Использование Git и платформы GitLab обеспечивает прозрачность процессов. Участники команды могут асинхронно просматривать и комментировать итеративные изменения, что улучшает качество спецификаций и кода.
Гибкие инструменты использования GitLab:
GitLab предоставляет широкий набор инструментов для работы с проектами, что создает потенциал для роста и дальнейшего развития. Например, использование пайплайнов для автоматизации тестирования и развертывания спецификаций, широкий выбор готовых интеграций с такими сервисами, как Telegram, Notion, Jira, Google Docs, а также возможности для мониторинга и аналитики.
Сейчас мы активно экспериментируем над автоматизированным тестированием спецификаций, расскажем об успехах в будущих статьях!
Совместная работа:
Простота и безопасность работы в команде с возможностью параллельного редактирования. Аналитики, разработчики и техписы могут одновременно вносить изменения, не опасаясь конфликтов. Например, пока один аналитик работает над спецификацией, другой может заниматься анализом требований, а разработчик уже начинает писать код на основе текущей версии. Влитие веток друг в друга позволяет специалистам сообщать, когда они закончили свою часть работы, и отправлять чистовую версию на проверку в чужую ветку при помощи merge request (см. «Диаграмма ветвления git для команды разработки»).
Интеграция с процессами разработки:
Спецификации могут находиться рядом с кодом, что облегчает их использование и обновление в процессе разработки. Это позволяет разработчикам и ревьюерам сразу видеть требования к функциональности прямо в репозитории, не переключаясь между различными системами.
Единая точка правды:
Все спецификации хранятся в репозиториях разрабатываемых продуктов, что упрощает доступ и поиск необходимой информации для всех членов команды.
БОльшая независимость от сторонних инструментов:
Хранение данных и документации на собственных серверах или в частных облаках снижает риски, связанные с блокировками и санкциями, обеспечивая полный контроль и защиту информации.
Процесс работы с ветками
Мы разработали однозначный процесс работы с ветками в Git, чтобы обеспечить явное разделение обязанностей и минимизировать возможность конфликтов. Вот как это работает:
Шаг 1: Создание ветки для каждой задачи (Story)
При переходе задачи в статус Backlog (to do) аналитик создает ветку в нашем репозитории. Название ветки должно соответствовать номеру и теме задачи, например, STR000000000-new-feature. Мы решили включать название задачи в имя ветки, чтобы аналитикам было проще искать нужную ветку. Если идет восполнение технического долга и участвует только аналитик, можно создать ветку по модулю и отводить её сразу же от dev.
Шаг 2: Создание подветок для спецификаций
От основной ветки создаются подветки для спецификаций (например, STR000000000-spec-new-feature). Аналитик работает над спецификацией только в этой ветке.
Шаг 3: Создание подветок для текстов и переводов
При необходимости, создаются ветки для текстов и переводов (например, STR000000000-text-new-feature). Технический писатель работает над текстами в этой ветке. Каждая подветка предназначена для определенного этапа работы: задачи, спецификации, тексты. Это позволяет различным специалистам работать параллельно, не мешая друг другу. Также это позволяет специалистам сообщать, когда они закончили свою часть работы, и отправлять чистовую версию на проверку в чужую ветку при помощи merge request.
Шаг 4: Создание спецификации
Спецификация создается аналитиком, когда задача находится в статусе Backlog (to do). По окончании этого этапа спецификация должна содержать все требования и связи с элементами бэклога. Для перехода в Backlog (done) создается merge request в STR000000000-text-new-feature и проходит проверки.
Шаг 5: Проверка и вливание изменений
Создается Review Task в нашей системе SimpleOne для проверки merge request командой (Product Owner для проверки бизнес-требований, тестировщик для написания тест плана, разработчик). Тимлида назначают ответственным за проверку, поскольку он лучше всех знает архитектуру и может оценить реализуемость изменений. Это также делает процесс более асинхронным, что хорошо для командной работы (исследования показывают, что асинхронная работа повышает продуктивность и удовлетворенность сотрудников). Тимлид вливает MR после получения «ОК» от всех проверяющих.
Шаг 6: Переход в статус Backlog (done)
После влития в STR000000000-text-new-feature, задача переходит на стадию Backlog (done). Разработчик видит чистовую и проверенную спецификацию в своей ветке и может начать работу только над тем, что есть в его ветке. Тестировщик может начинать работу над тест‑планом. Аналитик может вносить изменения в своей «черновой» ветке.
Если изменения в спецификации потребуются на более поздних этапах, создается новый Review Task и проводится повторное ревью командой. Так мы уверены том, что изменения в спецификации не останутся без внимания: Product Owner проверит бизнес-требования, тестировщик обновит тест-план, разработчик внесет изменения в код.
Решение merge конфликтов
В случае возникновения merge конфликтов, вопрос решается синхронно на встрече или асинхронно по инструкции, чтобы минимизировать задержки в разработке.
Результаты эксперимента
К этому моменту, полгода как мы закончили эксперимент и используем этот подход в повседневной деятельности. Результатыь:
Мы улучшили инструментарий аналитиков, добавив инструменты разработчиков, что повысило общий уровень их квалификации.
Адаптация к новым инструментам прошла быстрее, чем мы ожидали, и заняла менее месяца для сотрудников без опыта работы с GitLab.
Cократилось время на проверку требований со стороны команды разработки — теперь ревью выполняется на 40% быстрее в среднем.
Как со стороны разработки, так и со стороны QA возросло участие в обсуждении спецификаций и контроле качества требований.
Уменьшилось количество дефектов в продукте благодаря тому, что тестировщик теперь пишет тест-планы и проверяет продукт на основе спецификаций, в которых учитываются edge cases всей командой.
Мы привлекли технических писателей к процессу работы в Git, что позволило нам более удобно проверять текстовые материалы.
Учитывая успешные результаты эксперимента, следующим логичным шагом в развитии подхода будет внедрение AI-инструментов для разработки и управления спецификациями требований. Например, это может включать автоматическую проверку корректности формулировок, пунктуации, орфографии и выявление противоречий с другой информацией о продукте.
Высказывайтесь и присоединяйтесь к обсуждению в комментариях! Расскажите, как вы управляете спецификациями в проектах. Возможно, ваш опыт поможет другим читателям найти лучшие решения для своих команд. Не забудьте подписаться на наш блог, чтобы не пропустить новые статьи о передовых практиках разработки.
В одной из следующих статей расскажем о темплейтах, которые мы используем для хранения спецификаций.
Комментарии (9)
sergey_prokofiev
18.09.2024 09:55+4Удивлен тем что рассматривают аж целых 2 варианта: гугл док и спецификацию как код.
Миновав валом промежуточных вариантов, в том числе все возможные трекинг сервисы - та же жира.
Но раз я этот бред асилил, то напишу развернуто.
"Спецификация" - это сферический конь в вакууме. Она бывает разной и(вы удивитесь) есть валом инструментов для работы с разными видами спецификации.
Начинается все со списка бизнес требований к продукту и любое хранилище данных, включая гул докс - норм. Выбор конкретного решения зависит от стандартов компании, ее размеров, и так далее. Можно ли эту документацию трекать в гите - скорее нет чем да, потому что стейкхолдеры - это бизнес которому все эти гиты, бранчи, мердж реквесты и тд и тп не нужны. А историю изменений трекают все сколько-нибудь популряные сервисы.
Затем из списка требований получается техническое предложение по реализации. Можно ли его трекать в гите и апдейтить вместо с кодом? Скорее да чем нет. Тут уже стейхолдеры технари, нам такое нравится. Но есть технические сложности которые надо порешать: выбор формата написания текста(.docx файлы при мерже нечитабельны) и формат рисования картинок - опять таки решаемо, но немного геморно. Есть ли альтернативы? Валом, начиня с того же гугле докса. Главный минус альтернатив - оторванность от кода. Но как пишут авторитетные дядьки "documentation must be up to date but not too up to date".
После документации пишут код, которsй конечно же все привыкли видеть в гите. Код пишут не просто так, а с привязкой к некоторым "задачам" и очевидным же тайтрекингом. Можно ли трекать "задачи" в гите - можно, но есть валом инструментов в которых их трекать попросту удобней. Включая статистику по ним, в том чсиле построение burndown и прочих других графиков и отчетностей, которые работают из коробки в десятках продуктов. Кто стейхолдеры этих документов - правильно, пм-ы и прочие не технари, которые привыкли работать со своими инструментами, и гит "из коробки" им не посчитает загруженость WBS.
А параллельно с кодом иногда пишут тесты. Включая описание тест кейсов и формирование на их основе тест сетов и потом - трекание запусков этих тест сетов и документирование результатов(включая создание неизбежных багов). Можно ли их трекать в гите? Конечно можно, но насколько это удобно? Наверное не очень, хотя есть варианты. Стейкхолдеры тут очевидно QA, BA, PMs. Которые опять таки не очень дружат с гитом и снова любят всякие статистики которые делаются в 2 клика мыши в любом специализированном сервисе.
Следующий этап документирования - это некий юзер мануал, который опять таки пишут BA, и апдейтят с каждым релизом. Можно ли научить BA писать маркдауном и делать мердж реквесты? Наверное да, но зачем?
В общим идея трекать часть документации как код - интересная и здравая, но надо понимать ограничения этого подхода, включая назначение документов, типичные навыки разных стейхолдеров, наличие сервисов которые решают ряд задач из коробки эффективней чем "мы в одном бранче и доку и код проадейтили".
dvaskovskaya Автор
18.09.2024 09:55Спасибо за ваш комментарий. Вы затронули важные моменты, я вижу, что в вашем рассуждении присутствует смешение понятий таск-трекинга (управлением задачами) для разработки и управление изменениями в документации (нашем случае именно спецификации требований).
Управление задачами касаются процесса работы над проектом или продуктом, контроля сроков и распределения ресурсов, это отдельные инструменты нашего SDLC. Управление изменениями в спецификации в свою очередь так же выделенный процесс со своими артефактами и инструментами. Отрадно, что Ваш вывод повторяет посыл статьи, "идея трекать часть документации как код - интересная и здравая".
sergey_prokofiev
18.09.2024 09:55+1в вашем рассуждении присутствует смешение понятий таск-трекинга (управлением задачами) для разработки и управление изменениями в документации
отнюдь, я отдельно рассматриваю разные виды проектной документации. Вы же пишете только про «спецификации», даже не обьясняя, что вы под этим термином понимаете.
KReal
18.09.2024 09:55+1У нас очень хорошо зашло network rules as a code. В двух словах - раньше, чтобы пробить коннект с одного дата центра на другой (или тем паче в амазон или в какой-то внешний ресурс) нужно было заполнять огромных размеров DOC файл, отправлять его куда-то там и ждать согласования. Теперь просто делается пулл реквест, где в YAML файле пишется source и destination.
dvaskovskaya Автор
18.09.2024 09:55+2Да, для определенных задач git - это прекрасный инструмент. Как раз хотелось этой статьей подсветить, что git можно использовать не только для кода.
sergey_prokofiev
18.09.2024 09:55гугл докс тоже прекрасный инструмент. Вы вынесли 2 проблемы, которые у вас были в гугл докс и которые вы решили переходом на гит:
Отсутствие версионирования: Трудно было отслеживать изменения и возвращаться к предыдущим версиям спецификаций.
Трудности в совместной работе: Было трудно сообщать о конкретных изменениях в спецификации с течением времени. Процесс ревью спецификаций был муторным и синхронным.
В гугл докс есть версионирование и есть нотификация пользователей об изменении документа - вы решили процессную проблему заменой инструмента и модификацией процесса - хотя с инструментом все и так хорошо.
dvaskovskaya Автор
18.09.2024 09:55Спасибо за ваше мнение! Инструменты вроде Google Docs действительно имеют свои плюсы, но подходы к управлению документацией могут сильно различаться в зависимости от задач и процессов. Мы не можем согласиться с тем, что Google Docs полностью удовлетворяет наши потребности в управлении изменениями в спецификациях требований.
Многие из ваших вопросов, скорее всего, можно решить, если подробнее изучить подход docOps (например в сообществе https://t.me/docsascode). Этот метод помогает более эффективно управлять версионированием, совместной работой и прозрачностью изменений. Рекомендую обратить внимание на docOps — возможно, он окажется полезным и для вашего рабочего процесса.
Antra
Я не настоящий сварщик, возможно поэтому не совсем понял детали.
Аналитик, технический писатель чем в своих ветках занимаются? Могу предположить, что какждый правит собственный набор Markdown файлов. После merge другим становится видна сразу финальная версия (без черновиков), и это хорошо.
Но откуда тогда берутся конфликты? Разработчик правит файлы, подготовленные аналитиком?
Или аналитик и технический писатель все-таки не только над своими файлами работают, а добавляют комментарии (docstring) непосредственно в код?
dvaskovskaya Автор
Возможная причина конфликта может заключаться в том, что аналитики часто работают параллельно над несколькими историями. Например, в ветке STR0000000000-tema-istorii перед слиянием в dev может возникнуть конфликт, если другая параллельная история была интегрирована раньше.
Аналогичная ситуация может произойти и с другими членами команды при вливании STR0000000000-tema-istorii в dev, например, с разработчиками.
В результате конфликт может возникнуть как в файле аналитика, так и в файле разработчика, что требует совместного решения обеих сторон. Подобные ситуации случаются редко, и у нас разработаны процедуры для их оперативного разрешения как в синхронном, так и в асинхронном режиме.