Введение

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

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

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

Комментарии (9)


  1. Antra
    18.09.2024 09:55

    Я не настоящий сварщик, возможно поэтому не совсем понял детали.

    Аналитик, технический писатель чем в своих ветках занимаются? Могу предположить, что какждый правит собственный набор Markdown файлов. После merge другим становится видна сразу финальная версия (без черновиков), и это хорошо.

    Но откуда тогда берутся конфликты? Разработчик правит файлы, подготовленные аналитиком?

    Или аналитик и технический писатель все-таки не только над своими файлами работают, а добавляют комментарии (docstring) непосредственно в код?


    1. dvaskovskaya Автор
      18.09.2024 09:55

      Возможная причина конфликта может заключаться в том, что аналитики часто работают параллельно над несколькими историями. Например, в ветке STR0000000000-tema-istorii перед слиянием в dev может возникнуть конфликт, если другая параллельная история была интегрирована раньше.

      Аналогичная ситуация может произойти и с другими членами команды при вливании STR0000000000-tema-istorii в dev, например, с разработчиками.

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


  1. 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 писать маркдауном и делать мердж реквесты? Наверное да, но зачем?

    В общим идея трекать часть документации как код - интересная и здравая, но надо понимать ограничения этого подхода, включая назначение документов, типичные навыки разных стейхолдеров, наличие сервисов которые решают ряд задач из коробки эффективней чем "мы в одном бранче и доку и код проадейтили".


  1. dvaskovskaya Автор
    18.09.2024 09:55

    Спасибо за ваш комментарий. Вы затронули важные моменты, я вижу, что в вашем рассуждении присутствует смешение понятий таск-трекинга (управлением задачами) для разработки и управление изменениями в документации (нашем случае именно спецификации требований).

    Управление задачами касаются процесса работы над проектом или продуктом, контроля сроков и распределения ресурсов, это отдельные инструменты нашего SDLC. Управление изменениями в спецификации в свою очередь так же выделенный процесс со своими артефактами и инструментами. Отрадно, что Ваш вывод повторяет посыл статьи, "идея трекать часть документации как код - интересная и здравая".


    1. sergey_prokofiev
      18.09.2024 09:55
      +1

      в вашем рассуждении присутствует смешение понятий таск-трекинга (управлением задачами) для разработки и управление изменениями в документации

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


  1. KReal
    18.09.2024 09:55
    +1

    У нас очень хорошо зашло network rules as a code. В двух словах - раньше, чтобы пробить коннект с одного дата центра на другой (или тем паче в амазон или в какой-то внешний ресурс) нужно было заполнять огромных размеров DOC файл, отправлять его куда-то там и ждать согласования. Теперь просто делается пулл реквест, где в YAML файле пишется source и destination.


    1. dvaskovskaya Автор
      18.09.2024 09:55
      +2

      Да, для определенных задач git - это прекрасный инструмент. Как раз хотелось этой статьей подсветить, что git можно использовать не только для кода.


      1. sergey_prokofiev
        18.09.2024 09:55

        гугл докс тоже прекрасный инструмент. Вы вынесли 2 проблемы, которые у вас были в гугл докс и которые вы решили переходом на гит:

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

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

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


        1. dvaskovskaya Автор
          18.09.2024 09:55

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

          Многие из ваших вопросов, скорее всего, можно решить, если подробнее изучить подход docOps (например в сообществе https://t.me/docsascode). Этот метод помогает более эффективно управлять версионированием, совместной работой и прозрачностью изменений. Рекомендую обратить внимание на docOps — возможно, он окажется полезным и для вашего рабочего процесса.