Введение
Процесс ревью технических требований в мире аналитики уже давно стал привычным шагом в этапах работы с документацией. После написания ТЗ оно отдается коллеге на вычитку, чтобы на самом ранней стадии отыскать возможные ошибки или пропущенные моменты. Как всем известно, исправление ошибки на этапе аналитики стоит дешевле всего.
Вернемся к истокам. Ревью документации в нашем понимании
Я знаю, что во многих командах само ревью запускалось с большим скрипом. Гордость и характер участников команды, а также не самый удобный подход к ревью сильно усложнял сам процесс.
Из распространенного:
«Да кто он такой, чтобы поправлять меня?»
«У них же нет этой компетенции?»
«Ревьювер должен так проверить ТЗ, чтобы мог его сам показать бизнесу»
И т. д.
Когда мы запускали ревью, то постарались максимально объективно и с уважением подойти к этому процессу
Какие глобальные аксиомы мы для себя определили:
Каждый может ошибиться или что-то пропустить.
От ревьювера не требуется вычитки ТЗ с максимальным погружением в постановку – часто это достаточно сложно и трудозатратно.
Ревью не должно занимать много времени.
Чем руководствуется ревьювер, читая ТЗ:
Написанная постановка должна быть понятна не погруженному в контекст человеку.
Все утверждения должны быть логичны.
Документ должен соответствовать шаблону ТЗ — должны быть заполнены все разделы, либо удалены, если не требуются.
После прочтения документа ревьюверу понятна общая идея задачи и к ней нет вопросов.
Что делаем, если по ТЗ есть замечания:
Вопрос оставляется встроенным комментарием в соответствующем месте документа.
-
По завершении ревью:
Оставляли комментарий в Jira задаче о завершении ревью.
Дублировали в чатик в Teams.
Jira на основании комментария делала рассылку ревьюверу, что нужно почитать вопросы.
Автор ТЗ отвечал на все комментарии и вносил правки в ТЗ, если это требовалось.
Комментарий закрывается ревьювером, даже если автор ТЗ точно понимает, что вопрос решен.
Оценка исходного состояния
Выше мы с вами погрузились в то, какой процесс ревью у нас есть и как мы его проводим. Думаю, что многие из вас заметили, что есть и дублирующие действия, и многое решается административным подходом и самоорганизацией
Настроить правила в почте, чтобы не пропускать назначенную на ревью задачу.
Настроить правила в почте, чтобы следить за вопросами по ТЗ.
Не забыть написать в Jira задачу.
Не забыть написать в Teams.
Не потерять фокус на ревью среди других задач.
Почему я задумался об автоматизации
После того как Atlassian выпустил новый инструмент Comala, который помогает настроить автоматизацию ревью через построение Бизнес-процесса (БП), наш ЦК аналитики погрузился в инструмент и написал инструкцию о том, как настроить базовую автоматизацию.
В старой команде нас было трое аналитиков, и на ревью мы отдавали какому-то другому аналитику, одному. Получалось, что коммуникация и процесс взаимодействия были очень простые, поэтому я не стал в тот момент изучать новый инструмент, так как считал его лишь усложнением процесса.
Но после того, как я поменял команду и стал там единственным аналитиком, а документация стала проходить ревью у всей команды (7 человек), стало понятно, что нужно как-то автоматизировать работу с документацией. Чтобы сделать лучше, чем ручное переключение статусов в документе и отслеживание его через макрос Requirements.
Первая версия автоматизации
Прочитав инструкцию и соединив функционал Comala с тем, как мы ведем ревью, я собрал свой первый вариант БП
Также его можно посмотреть в виде кода
{workflow:name=Template for Habr|key=spaceworkflow--1938429722|label=habr_temp|adminusers=IKhakharev|stickylabels=habr_temp|content=pages}
{state:In Progress|taskable=true}
{state-selection:states=Review}
{state}
{state:Review|approved=Approved|taskable=true|colour=#0052CC}
{state-selection:states=In Work|user=ikhakharev}
{approval:Review|user=&IKhakharev|approvelabel=Ставлю Approve|rejectlabel=Оставлены комменты}
{state}
{state:Approved|final=true|hideselection=true}
{state-selection:states=In Work|user=ikhakharev}
{state}
{trigger:statechanged|state=Review}
{send-email:user=ikhakharev |subject=Habr template ревью ТЗ}
Назначена на ревью: @page@
{send-email}
{trigger}
{trigger:statechanged|state=Approved}
{send-email:user= ikhakharev |subject=Habr template ревью ТЗ}
Ревью завершено: @page@
{send-email}
{trigger}
{workflow}Общие настройки вокруг БП
-
Создавал я БП как процесс пространства (Space template)
Можно создавать процесс и для страниц, но в нем меньше возможностей
-
Для нашего БП мы добавили метку и sticky-метку
При добавлении метки на страницу к этой странице автоматически подтягивается БП для ревью документа. В противном случае при включении шаблона данный процесс появится на всех документах пространства, а это далеко не всегда нужно.
Sticky-метка говорит о том, что удалить ее со страницы с ТЗ может только админ, который также задается в настройках БП.
Ещё наш процесс ревью делается без возвратов в статус Работа из процесса ревью. То есть автор переводит документ на ревью и документ находится в этом статусе, пока по нему идут все правки и изменения. По факту всех исправлений документ уже переводится в состояние Approve. И даже в этом состоянии можно что-то обновлять – помарки, опечатки. Для того чтобы наш процесс работал именно так, я выключаю настройку сброса статуса при обновлении страницы.
Настройка Бизнес-Процесса
В наличии имеем 3 статуса
In Progress – стартовый статус процесса, в нем будет сразу находиться ТЗ, когда добавят метку на страницу.
Review – статус, в котором будет проходить то самое ревью.
Approve – финальный статус процесса, в который будет переведен наш документ по завершении проверки всеми участниками команды.
Настройка статусов
Для каждого статуса мы можем сделать определенную настройку, которая будет определять его ключевые параметры:
Transitions – эта настройка определяет, какие переходы возможны из/в этот статус.
Approvals – в этом разделе мы делаем все настройки относительно ревью.
Tasks – тут мы можем дополнительно настроить задачи, которые будут появляться на странице и работать как некий чек-лист
Меня интересовали только два первых параметра.
Для первого статуса In Progress
Для этого статуса я настроил только переход. То есть возможность автором документа перевести статус документа в следующий. Собственно, в статус Review
На странице с документом мы видим как раз доступную для нажатия кнопку Submit.
Панель работы со статусами появляется при нажатии на статус документа.
Настройка статуса Review
Мы также настраиваем переход, который говорит о том, что когда документ будет заапрувлен, он автоматически перейдет в статус Approved.
И теперь мы настраиваем уже само ревью, так система понимает, что именно в этом статусе пользователи будут согласовывать документ.
В данной настройке мы указываем:
Название этапа согласования.
Как будут назначаться ревьюверы.
Кто они будут.
В моем случае я определил настройку так:
Название процесса согласования – Review.
-
Метод назначения ревьюверов – жесткое назначение указанных ревьюверов
Также можно выбрать вариант указания из списка или просто сказать, что согласовать может кто угодно.
Списком указаны те, кто будет согласовывать.
Так как в новой команде у меня ревью документа всегда проводит вся команда, то мне удобнее один раз указать всех участников команды и при переводе документа в статус Review все они будут автоматически назначены как ревьюверы.
Как это выглядит на документе
После назначения на ревью каждый из участников команды автоматически назначается ревьювером, и при открытии управляющего окошка на документе он увидит новое окно, на котором можно принять решение о документе.
Approved – у ревьювера нет замечаний и он согласовывает документ.
Reject – у ревьювера есть замечания и он хочет об этом сообщить.
Тут мы вспоминаем этап, когда мы настраивали переход из статуса Review в статус Approved. Так вот – когда все ревьюверы документа нажали на кнопку Approved, документ автоматически переключится с согласованного финального состояния и документ будет Approved!
Кнопка Reject в данном случае позволяет переводить документ в какой-то другой статус, к примеру, если хотя бы один человек нажал на эту кнопку, то документ отправляется назад — в статус In Progress.
Как я рассказывал в самом начале, мы не возвращаем документ в работу и проводим ревью с правками в рамках статуса Review, поэтому мы просто договорились эту кнопку не нажимать.
И осталось настроить статус Approved
В данном случае все просто — если по документу требуются доработки или критические изменения, то автор/администратор/ответственный аналитик должен иметь возможность вернуть документ в работу. Что мы, собственно, и настраиваем в параметре Transitions
В данной настройке я использую
Вариант смены статуса Select, что позволяет более гибко работать с переходом.
Ограничение: совершить переход могу только я (так как являюсь единственным аналитиком и ответственным за документацию).
Так выглядит заапрувленный документ.
В панели управления статусом видно, что я могу перевести его обратно в работу – статус In Progress
Рассылка
Ну и, конечно, рассылка, которая становится одной из основных плюшек автоматизации. Рассылка добавляется с помощью Trigger’ов. Они отлавливают изменения статуса БП и автоматически отправляют рассылку тем, кому требуется. Триггеры можно указать либо в отдельном разделе при редактировании шапки БП, либо сразу писать в коде.
Давайте поближе посмотрим на триггеры, которые у нас получились:
{trigger:statechanged|state=Review}
{send-email:user=ikhakharev |subject=Habr template ревью ТЗ}
Назначена на ревью: @page@
{send-email}
{trigger}
{trigger:statechanged|state=Approved}
{send-email:user= ikhakharev |subject=Habr template ревью ТЗ}
Ревью завершено: @page@
{send-email}
{trigger} -
В заголовке каждого триггера:
Написан метод, по которому он отработает statechanged.
Написан статус, который должен быть, когда триггер отработает (в который переключился процесс).
-
В теле используется стандартный метод send-email. Настройки письма достаточно гибкие.
User = ikhakharev - определяет, кому будет отправлена рассылка. В данном случае мы задаем пользователя, которому будет отправлена рассылка.
Subject = Habr template ревью ТЗ – определяет тему будущего письма, что очень удобно для дальнейшей настройки правил в почте.
Ревью завершено: @page@ - тело письма. Может быть абсолютно любым. При этом есть возможность динамически вытащить название страницы, для которой происходит данная рассылка
Пример получившегося письма:
Мониторинг документов
Вся эта автоматизация должна помогать не только переключать статусы на документе, но и группировать все документы, отслеживать их состояния в одном месте для всей команды.
Для этого предоставляется макрос Отчет о состоянии документа.
Его настройка достаточно проста.
Кому назначено утверждение – Указываем динамическую метку @Self , то есть текущий пользователь.
Набор столбцов, по запросу и удобству – в моем случае мне интересно: Название документа, его статус, состояние согласующих (кто согласовал, кто нет) и когда документ был изменен последний раз.
Указывается метка, по которой добавляется ревью на страницу – если у вас несколько процессов, то так очень удобно разделять
И количество документов на страницу, чтобы влезали все
Что я увижу в отчете
Итоги базовой автоматизации
В итоге с этой не самой сложной настройкой мы получили:
Каждый документ теперь имеет процесс согласования.
Информирование о назначении на ревью происходит автоматически.
По завершении ревью участник команды просто ставит Approve, и этого достаточно для того, чтобы документ автоматом перешел в согласование, не нужно информировать об этом через каналы связи.
Коммуникация через Teams / Jira / почту упрощается до процесса синхронизации о том, не забыл ли человек про ревью и что надо бы его посмотреть (это спокойно можно делать на летучках).
Все участники команды через макрос могут видеть все назначенные на них документы на ревью и планировать свое время для их вычитки.
Аналитик или любой другой участник команды, кому это нужно, может видеть полный список документов и состояние его согласования, на основании чего может оценивать и прогресс по ревью.
Всем большое спасибо за внимание! :-)