Всем привет. Меня зовут Татьяна Цикунова. Я системный аналитик в компании МойСклад. В этой статье расскажу о том, как организовать оперативный обмен информацией между участниками проекта и поддерживать документацию в актуальном состоянии. Отдельное внимание уделю работе с таск-трекерами — подробно опишу шаблон тикета, который успешно используется в нашей компании. Однако - если вы работаете без трекера задач, например, в ворд-файлах, суть от этого не меняется —такой подход работает и с другими инструментами.
Я документирую системы больше 3 лет, и за это время успела поработать в разных сферах. Начинала в финтехе, где успела поработать в разных командах. Потом перешла в МойСклад — здесь углубилась в e-commerce направление. Сейчас вместе с командой делаем интеграции с интернет-магазинами и маркетплейсами. За годы работы я убедилась, что не существует единого стандарта ведения документации — каждая компания и даже отдельные команды внутри одной организации вырабатывают свои подходы.
Однажды в МоемСкладе мы задумались: почему бы не начать системно собирать важные данные, которые появляются на разных этапах разработки? Ведь эти сведения могли бы стать отличной основой для обновления документации к реализованному ПО. Так и появились требования и рекомендации по описанию тикета.
Основные проблемы при работе с постановкой задач
Сначала давайте выделим проблемы, которые возникают при работе с документацией:
Изменение постановки задачи в процессе разработки ПО
Изменения могут быть разные. Например, в процессе разработки появляется альтернативный взгляд на решение проблемы/реализации исходной модели требований. Тогда приходится придумывать новую логику и описывать ее в постановке. Или на каком-либо из этапов реализации изменилось законодательство, и пришлось переписывать бизнес требования. Если не фиксировать апдейты, то на выходе у участника разработки, который будет обновлять документацию реализованного ПО, не будет актуальной информации.Информация хранится в разных местах
Разработчики и тестировщики вынуждены фиксировать решения и изменения, которые возникли в процессе производства в разных местах: треды в Slack/Telegram/Mattermost, письма на почте, устные договоренности. Эта информация легко теряется, а единого места для ее хранения нет.В процессе работы возникают сложности с отслеживанием изменений, поскольку в проекте много участников
Итак, основной вопрос: Как нам работать над задачей так, чтобы было легко и просто фиксировать изменения или детали фактической реализации на протяжении всей работы? Логичным предложением будет фиксировать все важное в одном месте. Тикет становится главным документом, сопровождающим задачу на всех этапах ее жизненного цикла. Поэтому логично использовать его как централизованное хранилище всей ключевой информации.
Шаблон тикета
Чтобы не заполнять тикет с нуля каждый раз, нужно позаботиться о создании шаблона. Этот процесс должен исходить из опыта команды/компании, из выстроенных процессов и потребностей.
Шаблон — это основа для автоматического заполнения тикетов. Хотя каждая команда может дополнять шаблон своими разделами (например, команды мобильной разработки добавляют информацию о версиях приложений), мы выделили общие обязательные блоки для всех. Такой подход позволяет любому сотруднику понять структуру чужого тикета.
Расскажу, как мы сделали такой шаблон в МоемСкладе.
Состав шаблона
Из чего состоит шаблон:
Бизнес-требования
Постановка задачи
Раздел Разработка
Раздел Тестирование
Раздел Миграция данных
Раздел Откат
А теперь давайте кратко пройдемся по каждому разделу, и посмотрим, какой информация вносится в каждый из них.
Раздел: Бизнес-требования
Это раздел бизнес-требований. Он заполняется в процессе заведения тикета. На этапе жизненного цикла TODO.
Его задача — зафиксировать наличие проблемы или пожелания, сформулировать исходное описание: нового процесса, функциональности, изменений UI и т.д.
Из описания должно быть понятно:
что это за изменение
мотивация — цель тикета (зачем) и заинтересованные в его исполнении (для кого)
ожидаемый результат
Описание может быть сделано в свободной форме. Желательно указывать в составе бизнес-требований цель разработки. Важно, чтобы формулировка задачи однозначно отражала ожидаемый результат.
Если триггером для заведения тикета стала ошибка, то нужно описать следующее:
Описание ошибки: Последовательность действий, которую выполнял пользователь. Скриншоты, видео, логи, переписки и другие материалы, которые могут помочь проанализировать ошибку.
Ожидаемый результат: ожидаемый результат, со ссылкой на требования к реализации - ссылка на Confluence (раздел <название раздела>), если он описан в документации.
Фактический результат: реальное состояние и поведение, его отличия от ОР, что происходит на самом деле у пользователя.
Раздел: Постановка задачи
Этот раздел заполняется до оценки трудоемкости тикета.
Его задача — подготовить тикет к этой оценке. Это этап первоначального планирования работ по тикету. Заполнение раздела выполняется на этапе жизненного цикла TODO. Он может заполняться любым членом команды во время разбора бэклога или в момент планирования. В дальнейшем этот раздел может быть уточнен в ходе работ.
Это обязательный раздел в любом тикете.
Подзаголовки раздела Постановка задачи
Доработки
Здесь можно описать набор планируемых изменений и доработок, в том числе приложить подробную спецификацию требований, системный проект и т.п.
Миграция
Если на этапе планирования понятно, что миграция понадобится, это нужно указать в данном разделе. Можно указывать как простой факт, что миграция понадобится, либо описать, какие именно изменения предполагаются, если есть ясность уже на этом этапе.
Конфигурации
Нужно указать, понадобятся ли изменения в конфигурациях.
Далее рассмотрим опциональные подзаголовки.
Фича флаг
Опционально. Есть возможность заранее продумать, нужен ли для данной задачи фича флаг, если да, то как с ним работаем.
Документация
Опционально. Тут можно перечислить, какие статьи в документации необходимо исправить или создать исполнителям тикета, если это требуется.
Дизайн и маркетинг
Опционально. Тут могут быть указаны: ссылка на задачу на UI дизайн; ссылка на макет дизайна в Figma; ссылки на задачи на перевод текстов; видео-инструкция к фиче; ссылка на задачу промо-картинки фичи.
Раздел: Разработка
Этот и последующие разделы заполняются на этапе жизненного цикла IN PROGRESS. За их заполнение отвечает разработчик. Главная цель раздела — рассказать, что именно было сделано в процессе работы над тикетом.
В преамбуле раздела нужно описать в терминах функциональности: что было изменено, исправлено или удалено; какая новая функциональность была добавлена.
Подраздел MR
В нем необходимо перечислить ссылки на MR по данной задаче. Их может быть несколько. Обычно несколько MR возникает, когда для одного тикета есть изменения в нескольких репозиториях.
Далее идут опциональные подразделы.
API методы
Опционально. Можно описать какие ручки были добавлены.
Логирование и метрики
Опционально. Разработчик описывает, как найти строчки в логах, как найти дашборд в Grafana и на какие метрики смотреть.
Изменения в библиотеках
Опционально.
Unit-тесты
Опционально. Если в процессе работы над тикетом были изменены или добавлены unit-тесты, можно указать, какую именно функциональность они покрывают. Это будет полезно при ревью.
Раздел: Тестирование
Этот раздел заполняет разработчик на этапе жизненного цикла IN PROGRESS. Основная задача раздела — передать имеющиеся у разработчика сведения о скоупе внесенных им изменений и их влиянии на существующую функциональность. Этот раздел позволяет тестировщику определить, на что следует обратить внимание при тестировании помимо того, что было напрямую отражено в требованиях (в постановке задачи), а также определить скоуп необходимого регрессионного тестирования. Этот раздел помогает ответить на 2 вопроса: «Какие изменения были внесены?», «На что эти изменения могут повлиять?».
Уже на этапе тестирования тестировщики добавляют артефакты своей работы (например, тест‑лист) в комментарии к тикету. Поскольку эти документы часто содержат большой объем информации, их неудобно добавлять в тело тикета.При работе над задачами, связанными с изменениями в продукте, процесс тестирования строится несколько иначе, чем при исправлении багов. В таких случаях тест‑план обычно разрабатывается заранее — либо на этапе проектирования, либо параллельно с разработкой. Этот документ сначала вносится в общую базу тестовой документации, а потом на него просто ставится ссылка в соответствующем тикете.
Раздел: Миграция
Стоит заметить, что этот раздел будет актуален не для всех команд. Для нас это было оправданно, поскольку значительная часть задач связана с миграциями данных.
Подразделы раздела Миграция
Название
Имя файла миграции.
Тип
Тип миграции бд — ONLINE или OFFLINE.
Время на stage
Замер времени выполнения миграции на stage-окружении.
Время на проде
Оценка времени выполнения миграции на проде, сделанная на основе выполненных замеров, а также с учетом того, что на проде одновременно работают много пользователей.
Физический смысл
Описание, какие таблицы, колонки меняются, какие данные добавляются.
Бизнес-смысл
Цель изменений схемы данных.
Раздел Откат
Здесь можно указать имя файла отката, если откат миграции реализован.
Время отката на stage
Замер времени выполнения отката миграции на stage-окружении.
Флоу работы с тикетом
Итак, мы видим, что шаблон достаточно гибкий, его можно адаптировать под нужды команды.
Шаблон в тикете также служит чек-листом на всех этапах работы. Это как дополнительные края у ведра, которое постепенно заполняется. Риски расплескать содержимое увеличиваются со временем. Часто команды сталкиваются с ситуациями, когда о фича-флаге вспоминают только на предрелизном этапе или забывают обновить документацию.
Давайте подведем итоги и посмотрим на краткий флоу работы с шаблоном тикета:
Инициатор изменений создает тикет
В настройках тикета выбирается функция “Применить шаблон”
Участники команды вносят требования и постановку
Разработка вносит детали реализации и рекомендации для тестирования
Тестировщики прикладывают артефакты, которые получили в процессе тестирования
По мере приближения тикета к релизу команда начинает готовить данные к обновлению документации реализованного ПО. Если источником описания фичи остается тикет, то данные в тикете также актуализируются.
Плюсы подхода
Гибкость в использовании. Можно выделить универсальные заголовки первого уровня, а заголовки последующих уровней сделать рекомендательными
Одно место для информации по задаче, которое в доступе на протяжении всего жизненного цикла работы над задачей
Быстрота применения. Использовать шаблон в тикете легко и очень просто
Шаблон также выполняет функцию чек-листа
Внедрение. Рекомендации
Пошаговый план внедрения нового шаблона тикетов:
Назначьте ответственного за разработку шаблона
Это должен быть человек, который глубоко понимает рабочие процессы команды. Его задача — собрать требования: какие разделы должны быть обязательным, какие — опциональными, какой уровень детализации требуется для разных типов задач.Оформите шаблон визуально и напишите инструкцию по заполнению.
Настройте автоподстановку в таск-трекере.
Проведите презентацию для команды с акцентом на преимущества использования инструмента.
Проведите пилотное тестирование для части пользователей.
Соберите обратную связь участников тестирования.
Доработайте шаблон при необходимости: устраните выявленные проблемы, дополните инструкции
Масштабируйте на все проекты