Всем привет. Меня зовут Татьяна Цикунова. Я системный аналитик в компании МойСклад. В этой статье расскажу о том, как организовать оперативный обмен информацией между участниками проекта и поддерживать документацию в актуальном состоянии. Отдельное внимание уделю работе с таск-трекерами —  подробно опишу шаблон тикета, который успешно используется в нашей компании. Однако если вы работаете без трекера задач, например, в ворд-файлах, суть от этого не меняется — такой подход работает и с другими инструментами.

Я документирую системы больше 3 лет,  и за это время успела поработать в разных сферах. Начинала в финтехе, где успела поработать в разных командах. Потом перешла в МойСклад — здесь углубилась в e-commerce направление. Сейчас вместе с командой делаем интеграции с интернет-магазинами и маркетплейсами. За годы работы я убедилась, что не существует единого стандарта ведения документации — каждая компания и даже отдельные команды внутри одной организации вырабатывают свои подходы.

Однажды в МоемСкладе мы задумались: почему бы не начать системно собирать важные данные, которые появляются на разных этапах разработки? Ведь эти сведения могли бы стать отличной основой для обновления документации к реализованному ПО. Так и появились требования и рекомендации по описанию тикета.

Основные проблемы при работе с постановкой задач

Сначала давайте выделим проблемы, которые возникают при работе с документацией:

1. Изменение постановки задачи в процессе разработки ПО
   Изменения могут быть разные. Например, в процессе разработки появляется  альтернативный взгляд на решение проблемы/реализации исходной модели требований. Тогда приходится придумывать новую логику и описывать ее в постановке. Или на каком-либо из этапов реализации изменилось законодательство, и пришлось переписывать бизнес требования. Если не фиксировать апдейты, то на выходе у участника разработки, который будет обновлять документацию реализованного ПО, не будет актуальной информации.

2. Информация хранится в разных местах
   Разработчики и тестировщики вынуждены фиксировать решения и изменения, которые возникли в процессе производства в разных местах: треды в Slack/Telegram/Mattermost, письма на почте, устные договоренности. Эта информация легко теряется, а единого места для ее хранения нет.

3. В процессе работы возникают сложности с отслеживанием изменений, поскольку в проекте много участников

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

Шаблон тикета

Чтобы не заполнять тикет с нуля каждый раз, нужно позаботиться о  создании шаблона. Этот процесс должен исходить из опыта команды/компании, из выстроенных процессов и потребностей.

Шаблон —  это основа для автоматического заполнения тикетов. Хотя каждая команда может дополнять шаблон своими разделами (например, команды мобильной разработки добавляют информацию о версиях приложений), мы выделили общие обязательные блоки для всех. Такой подход позволяет любому сотруднику понять структуру чужого тикета.

Расскажу, как мы сделали такой шаблон в МоемСкладе.

Состав шаблона

Из чего состоит шаблон:

• Бизнес-требования

• Постановка задачи

• Раздел Разработка

• Раздел Тестирование

• Раздел Миграция данных

• Раздел Откат

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

Раздел: Бизнес-требования

Это раздел бизнес-требований. Он заполняется в процессе заведения тикета. На этапе жизненного цикла TODO. 

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

Из описания должно быть понятно:

• что это за изменение

• мотивация — цель тикета (зачем) и заинтересованные в его исполнении (для кого)

• ожидаемый результат

Описание может быть сделано в свободной форме. Желательно указывать в составе бизнес-требований цель разработки. Важно, чтобы формулировка задачи однозначно отражала ожидаемый результат.

Если триггером для заведения тикета стала ошибка, то нужно описать следующее:

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

Ожидаемый результат: ожидаемый результат, со ссылкой на требования к реализации - ссылка на Confluence (раздел <название раздела>), если он описан в документации.

Фактический результат: реальное состояние и поведение, его отличия от ОР, что происходит на самом деле у пользователя. 

Раздел: Постановка задачи

Этот раздел заполняется до оценки трудоемкости тикета.

Его задача — подготовить тикет к этой оценке. Это этап первоначального планирования работ по тикету. Заполнение раздела выполняется на этапе жизненного цикла TODO. Он может заполняться любым членом команды во время разбора бэклога или в момент планирования. В дальнейшем этот раздел может быть уточнен в ходе работ.

Это обязательный раздел в любом тикете.

Подзаголовки раздела Постановка задачи

Доработки

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

Миграция

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

Конфигурации

Нужно указать, понадобятся ли изменения в конфигурациях.

Далее рассмотрим опциональные подзаголовки.

Фича флаг

Опционально. Есть возможность заранее продумать, нужен ли для данной задачи фича флаг, если да, то как с ним работаем.

Документация

Опционально. Тут можно перечислить, какие статьи в документации необходимо исправить или создать исполнителям тикета, если это требуется.

Дизайн и маркетинг

Опционально. Тут могут быть указаны: ссылка на задачу на UI дизайн; ссылка на макет дизайна в Figma; ссылки на задачи на перевод текстов; видео-инструкция к фиче; ссылка на задачу промо-картинки фичи. 

Раздел: Разработка

Этот и последующие разделы заполняются на этапе жизненного цикла IN PROGRESS. За их заполнение отвечает разработчик. Главная цель раздела — рассказать, что именно было сделано в процессе работы над тикетом.

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

Подраздел MR

В нем необходимо перечислить ссылки на MR по данной задаче. Их может быть несколько. Обычно несколько MR возникает, когда для одного тикета есть изменения в нескольких репозиториях.

Далее идут опциональные подразделы.

API методы

Опционально. Можно описать какие ручки были добавлены.

Логирование и метрики

Опционально. Разработчик описывает, как найти строчки в логах, как найти дашборд в Grafana и на какие метрики смотреть.

Изменения в библиотеках

Опционально.

Unit-тесты

Опционально. Если в процессе работы над тикетом были изменены или добавлены unit-тесты, можно указать, какую именно функциональность они покрывают. Это будет полезно при ревью.

Раздел: Тестирование

Этот раздел заполняет разработчик на этапе жизненного цикла IN PROGRESS. Основная задача раздела — передать имеющиеся у разработчика сведения о скоупе внесенных им изменений и их влиянии на существующую функциональность. Этот раздел позволяет тестировщику определить, на что следует обратить внимание при тестировании помимо того, что было напрямую отражено в требованиях (в постановке задачи), а также определить скоуп необходимого регрессионного тестирования. Этот раздел помогает ответить на 2 вопроса: «Какие изменения были внесены?», «На что эти изменения могут повлиять?».

Уже на этапе тестирования тестировщики добавляют артефакты своей работы (например, тест‑лист) в комментарии к тикету. Поскольку эти документы часто содержат большой объем информации, их неудобно добавлять в тело тикета.При работе над задачами, связанными с изменениями в продукте, процесс тестирования строится несколько иначе, чем при исправлении багов. В таких случаях тест‑план обычно разрабатывается заранее — либо на этапе проектирования, либо параллельно с разработкой. Этот документ сначала вносится в общую базу тестовой документации, а потом на него просто ставится ссылка в соответствующем тикете.

Раздел: Миграция

Стоит заметить, что этот раздел будет актуален  не для всех команд. Для нас это было оправданно, поскольку значительная часть задач связана с миграциями данных.

Подразделы раздела Миграция

Название

Имя файла миграции.

Тип

Тип миграции бд — ONLINE или OFFLINE.

Время на stage

Замер времени выполнения миграции на stage-окружении.

Время на проде

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

Физический смысл

Описание, какие таблицы, колонки меняются, какие данные добавляются.

Бизнес-смысл

Цель изменений схемы данных.

Раздел Откат

Здесь можно указать имя файла отката, если откат миграции реализован.

Время отката на stage

Замер времени выполнения отката миграции на stage-окружении.

Флоу работы с тикетом

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

Шаблон в тикете также служит чек-листом на всех этапах работы. Это как дополнительные края у ведра, которое постепенно заполняется. Риски расплескать содержимое увеличиваются со временем. Часто команды сталкиваются с  ситуациями, когда о фича-флаге вспоминают только на предрелизном этапе или забывают обновить документацию.

Давайте подведем итоги и посмотрим на краткий флоу работы с шаблоном тикета:

1. Инициатор изменений создает тикет

2.  В настройках тикета выбирается функция “Применить шаблон”

3.  Участники команды вносят требования и постановку

4. Разработка вносит детали реализации и рекомендации для тестирования

5. Тестировщики прикладывают артефакты, которые получили в процессе тестирования

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

Плюсы подхода

• Гибкость в использовании. Можно выделить универсальные заголовки первого уровня, а заголовки последующих уровней сделать рекомендательными

• Одно место для информации по задаче, которое в доступе на протяжении всего жизненного цикла работы над задачей

• Быстрота применения. Использовать шаблон в тикете легко и очень просто

• Шаблон также выполняет функцию чек-листа

Внедрение. Рекомендации

Пошаговый план внедрения нового шаблона тикетов:

1. Назначьте ответственного за разработку шаблона
   Это должен быть человек, который глубоко понимает рабочие процессы команды. Его задача  — собрать требования: какие разделы должны быть обязательным, какие  — опциональными, какой уровень детализации требуется для разных типов задач.

2. Оформите шаблон визуально и напишите инструкцию по заполнению.

3. Настройте автоподстановку в таск-трекере.

4. Проведите презентацию для команды с акцентом на преимущества использования инструмента.

5. Проведите пилотное тестирование для части пользователей.

6. Соберите обратную связь участников тестирования.

7. Доработайте шаблон при необходимости: устраните выявленные проблемы, дополните инструкции

8. Масштабируйте на все проекты