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

Всем привет! Я Алексей Толбин, главный системный аналитик в ПСБ, эту статью я написал вместе со своими коллегами — Никитой Резаевым, ведущим системным аналитиком, и Оксаной Резван, управляющим экспертом.

Все большие проекты начинаются с ТЗ. Оно задаёт вектор развития и ошибки, допущенные на этапе его проработки, могут привести к последствиям, которые в дальнейшем будет тяжело, а в некоторых случаях и невозможно исправить.

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

Что такое кросс-ревью?

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

Для проведения cross review мы с коллегами пользуемся картой компетенций. Её составляет технический лид. У нас, например, так, если смотреть с разбивкой по направлениям:

Что может случиться, если не проводить кросс-ревью

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

Ошибки, проросшие из непроверенного ТЗ, могут проявиться на этапе разработки — это лучший вариант, ведь аналитик ещё успеет переписать ТЗ, а разработчик — переделать код. Хотя времени, конечно, жалко. Либо они проявятся уже на стадии опытной эксплуатации продукта. Вот как в случае со Звездой Смерти :)

В общем, без кросс-ревью никуда.

Как мы проводим cross review

Cross review — это многосторонняя оценка документа ревьюверами. К процессу можно привлекать сразу несколько коллег, особенно если изменения затрагивают соседние команды. На схеме показано, как мы собираем команду на кросс-ревью.

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

Проверяя ТЗ, ревьювер идет по чек-листу — покажу его чуть ниже. Замечания оставляет в виде комментариев по тексту. Аналитик устраняет все ошибки и повторно идёт на ревью — процедура повторяется до тех пор, пока все замечания не будут устранены. После ревьювер закрывает задачу и передаёт ТЗ в разработку.

Чек-лист кросс-ревью

В этой статье мы приведём самые базовые пункты чек-листа. Без них никуда, но на самом деле их обычно больше. Можно добавить столько же разных пунктов и собрать не базовый минимум, а роскошный максимум :).

Цель: понятно ли сформулированы бизнес-цели. Зачем нужна данная доработка, понятна ли её цель каждому, кто будет читать ТЗ?
Инструмент: реалистичны ли технические требования? Возможно, задача слишком большая и она не войдёт в один релиз. Тогда её можно декомпозировать. Или, например, аналитик предложил сделать новый сервис, а уже существует готовое решение, можно не пилить свой велосипед.
Защита: учтены ли риски и уязвимости. Стоит проверить, нужно ли согласовывать эти требования с безопасниками.
Независимая проверка: есть ли взгляд со стороны. Нужно ли привлекать коллег из других команд на ревью?
Версионность: есть ли механизм версионирования. На каждой странице ТЗ мы ведем табличку — историю изменений, аналитик указывает в ней, какие правки были внесены (в рамках какой задачи и какая это версия ТЗ). Ревьювер проверяет, все ли корректно указал аналитик в этой табличке.
Единый подход: У нас есть правила оформления ТЗ, которых должен придерживаться каждый аналитик. Если что-то не так, ревьювер это подсвечивает. Это сделано, чтобы всем было удобно сопровождать ТЗ и вообще читать документ.
Противоречия: смотрим, чтобы не закрались логические баги, а все ссылки были верно указаны. Ну и подмечаем грамматические ошибки по тексту.

Какие ошибки отлавливаем в ТЗ чаще других

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

Ещё некорректное описание пользовательских сценариев. У нас был кейс, когда сделали продукт, но не реализовали кнопки для супервизоров, чтобы при технических неполадках или авариях они могли менять статус. Не учли пересечение возможных действий у ролей. Пришлось менять статусы скриптами для документов.

Ещё пример из области проблем с масштабируемостью. При формировании продукта надо обязательно думать на перспективу, как он будет расширяться. У нас был документ, в которым мы вели сметы. Со временем смет стало много, а через несколько лет документ вообще перестал открываться — падал в ошибку. Аналогично стоит внимательно смотреть на вопросы безопасности.

Версионирование ТЗ

Для упрощения работы команд и процесса ревью в частности, мы ведём версии документов. Отсутствие механизма актуализации версии в ТЗ — тоже типичная ошибка. Но отнесу это прямо в отдельную главу, потому что хочется рассказать подробнее.

В ТЗ у нас предусмотрена табличка с историей изменений:

Раньше бывало, что аналитики, указывая ссылку на версию, забывали менять предыдущую. При исправлении багов мы заходили в табличку и видели, что везде стоит ссылка на текущую версию — непонятно, в какой момент пришли изменения. Безусловно, можно поднять историю и найти всё, но на это уходит много времени.

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

Постепенно допиливаем систему. Например, дальше выяснили, что аналитикам нужны наименования цветов для удобства (особенно, когда нужно различать два похожих цвета). Тоже сделали. Вот в каком виде таблица существует сейчас:

Любой человек может открыть документ и, пользуясь версионированием, увидеть все текущие изменения, выделенные цветом (забронированным для конкретной задачи). Это позволяет разработчикам и тестировщикам быстрее искать изменённые или добавленные части — и, соответственно, быстрее делать ревью. Аналитику больше не нужно читать весь документ и искать по версионированию, какие там были сделаны правки. Он видит забронированный под задачу цвет и смотрит только окрашенные им изменения. Всё это здорово экономит всем время.

Чтобы закрепить практику, мы внедрили соглашение по выбору цветов. Аналитик не может забронировать первый попавшийся цвет. Он бронируется по порядку (сверху вниз по таблице) и один раз на задачу, т.е. некоторое количество документов, связанных с этой бизнес-задачей, будут окрашиваться в один и тот же цвет. Цвета бронируем в специальной таблице, указывая бизнес-задачу.

Цвета можно не выбирать, если задача выполняется с нуля (если не было документов с предыдущего спринта). Или если доработка совсем небольшая (в одно предложение, которое просто можно вставить ссылкой в Jira). Также проводя ретро по использованию палитры, мы поняли, что не обязательно каждому аналитику бронировать свой цвет. А ещё мы договорились, что если нет пересечений по документам, один и тот же цвет может бронировать несколько аналитиков.

И мы ввели резервные цвета. У нас много аналитиков, поэтому обычных цветов бывает недостаточно. Резервный цвет можно выбрать после того, как закончились основные. Ещё при выборе цвета мы также заводим задачу по возврату к дефолтному цвету, чтобы не забыть.

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

И напоследок

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

Спасибо за интерес к статье! Проходите в комментарии с вопросами по теме кросс-ревью. Подписывайтесь на блог ПСБ, мы с коллегами часто пишем здесь про разные полезные практики, которые помогают нам упростить труд. Можете написать, о чём по теме системного анализа вы бы ещё хотели почитать в статьях.

Как мы в ПСБ проводим кросс-ревью: чек-лист и прочая кухня