Введение

Для компании SimpleOne управление спецификациями требований было настоящей головной болью, требующей унификации подходов и учета потребностей разных команд. Мы стояли перед выбором: сделать свое решение для управления требованиями и сбора спецификаций или попробовать уже существующие практики. Концепция DocOps привлекла внимание тем, что помогает стандартизировать инструменты и навести порядок в хранении артефактов... В этой статье мы расскажем, как внедрили подход на основе docs as code, какие преимущества получили и какие трудности преодолели на пути.

О компании

SimpleOne — российский разработчик решений для автоматизации бизнес-процессов на базе собственной low-code платформы. Платформа помогает автоматизировать работу IT, HR, АХО и других подразделений компании, основываясь на лучших практиках предоставления сервисов (ITIL, VeriSM). Наши решения ориентированы на корпоративных и государственных клиентов, стремящихся к повышению эффективности и цифровой трансформации бизнеса.

Об авторах

Дарья Васьковская — аналитик в SimpleOne, экс-Яндекс. Участвую в запуске новых продуктов и объединяю опыт из разных сфер для поиска лучших решений

Сергей Бакин — руководитель направления бизнес-системного анализа SimpleOne, CBAP, более 12 лет опыта в IT.

Предыстория

До внедрения Doc as Code мы управляли требованиями через Google Docs, создавая спецификации для элементов бэклога, которые затем попадали в очередь задач продуктовых команд.. Это приводило к проблемам:

1. Отсутствие версионирования: Трудно было отслеживать изменения и возвращаться к предыдущим версиям спецификаций.

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

Мы решили провести эксперимент и создать свой подход — 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-инструментов для разработки и управления спецификациями требований. Например, это может включать автоматическую проверку корректности формулировок, пунктуации, орфографии и выявление противоречий с другой информацией о продукте.

Высказывайтесь и присоединяйтесь к обсуждению в комментариях! Расскажите, как вы управляете спецификациями в проектах. Возможно, ваш опыт поможет другим читателям найти лучшие решения для своих команд. Не забудьте подписаться на наш блог, чтобы не пропустить новые статьи о передовых практиках разработки.

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