Пользовательское требование — точка входа в документацию

Однажды мне пришла задача «реанимировать» документацию по фиче. Бизнес-логика, API, база данных, UI — всё было свалено в кучу, в одно сплошное полотно текста. И проблема была не столько в объёме, сколько в полном отсутствии структуры. Читать это было тяжело. Поэтому свои требования я организую иначе.

Я декомпозирую требования на отдельные артефакты. Каждая единица самодостаточна, а связи с остальными лишь дополняют картину всей фичи. Но тогда возникает вопрос: «Как ориентироваться в требованиях, если они разбросаны по wiki?». Для этого я и пишу пользовательское требование.

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

• ПТ — Пользовательское требование

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

• БП — Бизнес-правило

• ФТ — Функциональное требование

• НФТ — Нефункциональное требование

• ГИ — Требование к графическим интерфейсам

• СИ — Требование к системным интерфейсам

• ТД — Требования к данным

Если разбирать иерархию требований, то бизнес-требование будет стоять над пользовательским. Почему же тогда хабом является не оно? Чтобы ответить, давайте разберём разницу между ними:

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

Бизнес-требование — это зачастую не одна фича, а целый их набор. И каждая фича — это отдельное пользовательское требование. Все остальные требования относятся к самой фиче, а не к бизнесу.

Структура пользовательского требования

В работе я использую минимально достаточный шаблон. Он покрывает 90% потребностей команды, а остальные 10% выясняются в процессе. Что в нём есть:

• Метаданные

• Пользовательская история (User Story)

• Бизнес-контекст

• Критерии приемки

• Бизнес-процессы

• Бизнес-правила

• Ссылки на требования

В списке достаточно много слов с приставкой «бизнес». Точно ли системный аналитик должен его писать? Именно потому, что пользовательское требование стоит между бизнесом и реализацией — это продукт двух аналитиков: бизнес- и системного. Один рассказывает, зачем нужна эта фича, другой дополняет, что в этой фиче нужно реализовать. Но на практике зачастую я пишу документ целиком сам — бизнес-аналитику нужно только проверить и, при необходимости, поправить документ.

User Story — заглушка или полезный инструмент?

Почти каждый IT-шник слышал про пользовательские истории. Многие Agile-методологии рекомендуют использовать user story для описания бизнес-ценности фичи. Но в реальности я редко видел, чтобы их писали с пользой: зачастую их пишут просто для того, чтобы было.

Я всегда выбираю подход «если не надо, выкидывай». Это как с чердаком — люди хранят вещи до последнего, просто потому что «вдруг когда-то пригодится». Документация — это не чердак, она должна быть чёткой и понятной. Я тоже колебался, нужно ли оставлять пользовательскую историю, но в итоге понял, как она может помочь.

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

Во-вторых, это обозначение ролей пользователей — даже если у вас матричная система доступов, пользовательская история позволяет обозначить сразу же, кто именно может пользоваться этой фичей.

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

Бизнес-контекст

Бизнес-контекст — это краткое описание того, зачем фича нужна бизнесу. Не техническое обоснование, а причина существования.

Пример: на производстве комплектные заказы отслеживались в системе как отдельные. Логистам приходилось вручную следить, чтобы части комплекта не уехали по отдельности, что нередко случалось. Это влияло на стоимость доставки и лояльность клиента. Часть бизнес-контекста для такой фичи выглядела бы так:

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

Одно предложение — но через полгода любой человек в команде поймёт, зачем эта фича существует.

Критерии приемки: формат и значение

Критерии приемки — это фундамент для остальных требований. Они описывают как прямые пути использования фичи, так и краевые случаи. Это самый «живой» раздел пользовательского требования: по мере написания документации находятся всё новые условия, варианты использования фичи и исходы событий. Я всегда готов дополнить этот список, а с декомпозированной документацией это делается легко.

Структура у критериев простая: «дано», «когда», «тогда». Также важно их нумеровать — это позволяет легко ссылаться на них в требованиях. Я заполняю в виде таблицы: так проще читать и сложнее пропустить пункт.

В качестве примера покажу возможные критерии приемки для того же случая с комплектными заказами:

Бизнес-процессы

Бизнес-процесс показывает, как пользователь проходит через фичу. Гораздо сложнее описать процесс, если роли расплывчаты и всё живёт в матрице доступов. В этом случае я обобщаю до одного пользователя, а если необходимо, дописываю отдельные пермиссии в комментариях к действиям. Место этому артефакту скорее в бизнес-требовании, чем в пользовательском. Тогда зачем он здесь?

Бизнес-процессы обычно делаются в BPMN-диаграммах, которые позволяют описывать не только взаимодействие пользователей между собой, но и с системой. В своих схемах я уделяю больше внимания не действию человека, а тому, что происходит «под капотом»: какую именно реакцию вызывает каждое действие пользователя.

Может показаться, что не царское это дело, системному аналитику бизнес-диаграммы рисовать, да и вообще BPMN не про системную логику, но я возражу. Именно проработка взаимодействия пользователя с системой открывает бо́льшую часть краевых случаев. Процесс может быть не один, всё зависит от размера фичи. Но я не загоняюсь и не делаю диаграмму на каждый из возможных вариантов: только основные сценарии.

Инструмент для BPMN не принципиален. У меня на работе по регламенту они делаются через Camunda. По факту все делают где хотят: draw.io, FigJam, Miro. Важно, что я оставляю в документации файл для редактирования этого процесса, чтобы другой аналитик мог внести правки без меня.

Бизнес-правила

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

Системные требования

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

1. Функциональные требования

2. Требования к данным

3. Требования к системным интерфейсам

4. Требования к графическим интерфейсам

5. Нефункциональные требования

Чтобы этот раздел был полезен, формулировка требования записывается прямо в его заголовке. И каждое требование также нумеруется. Я использую нумерацию по ключу ([key-#]), как тикеты в Jira. Все сокращения с диаграммы выше — это и есть ключи. Все номера — сквозные, не привязаны к конкретному пользовательскому требованию: если в одном пользовательском требовании я закончил на номере 10, то в следующем я начну уже с номера 11. Так требование легко найти по номеру, даже вне контекста конкретной фичи.

«Зачем писать саму формулировку в требовании? Получается же слишком длинный заголовок!» — затем, что пользовательское требование становится самодостаточным: не нужно переходить по ссылке, чтобы понять суть. А бонус в том, что почти любая wiki подставляет название страницы в ссылку автоматически. Если я замечаю ошибку в формулировке, я исправляю её в заголовке — и это исправление автоматически применяется на всех страницах, где требование указано.

Оформление — важно!

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

В этой статье я уже разобрал полную структуру пользовательского требования. Осталось только собрать всё в шаблон:

Заголовок: #[ПТ-#] [Заголовок статьи]
Тело статьи:
> **Бизнес-требование:** [ссылка]
>
> **Статус:** [В проработке / В разработке / Завершено]
>
> **Автор:** @v.gromov
>
> **Задачи:**
>
> * EPIC: [ссылка]
> * STORY: [ссылка]

## **Описание**

### **Пользовательская история**

**Как** [роль пользователя / «пользователь»*],

**я хочу** [выполнить действие],

**чтобы** [достичь цели].
> * [пермиссии, в случае матричной системы доступов]

### **Бизнес-контекст**

[Пара предложений или абзац с бизнес-контекстом]

### **Критерии приемки**

| # | Дано | Когда | Тогда |
| --- | --- | --- | --- |

## **Бизнес-процесс**

[Изображение с бизнес-процессом]
[Ссылка на документ в онлайн-редакторе или сам файл с BPMN-диаграммой]

### **Бизнес-правила**

* [ссылки на бизнес-правила]

## **Системные требования**

### **Функциональные требования**

* [ссылки на функциональные требования]

### **Требования к данным**

* [ссылки на требования к данным]

### **Требования к системным интерфейсам**

* [ссылки на требования к системным интерфейсам]

### **Требования к графическим интерфейсам**

* [ссылки на требования к графическим интерфейсам]

### **Нефункциональные требования**

* [ссылки на нефункциональные требования]
 [1]

В начале — блок с мета-данными: ссылка на БТ, статус, автор, ссылки на задачи.

Как это выглядит на практике

[ПТ-7] Объединение заказов в комплекты для совместной отгрузки

Бизнес-требование: [БТ-2] Снижение затрат на доставку и повышение клиентской лояльности за счёт автоматизации комплектации заказов ^[2]
Статус: В проработке
Автор: @v.gromov
Задачи:

• EPIC: LOGISTICS-42 ^[2]

• STORY: LOGISTICS-118 ^[2]

Описание

Пользовательская история

Как логист*,
я хочу объединять заказы одного заказчика в комплект,
чтобы они отправлялись одной посылкой и система не позволяла кладовщику отгрузить часть комплекта отдельно.

пользователь с пермиссией canManageKits = true

Бизнес-контекст

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

Критерии приемки

#	Дано	Когда	Тогда
КП-1	Логист выбрал несколько заказов одного заказчика	Логист нажимает кнопку «Укомплектовать»	В системе создаётся комплект с выбранными заказами
КП-2	Существует комплект заказов	Кладовщик попытался отгрузить один заказ из комплекта (отсканировал в системе)	Система требует отсканировать и отгрузить другие заказы либо отменить отгрузку
КП-3	Существует комплект заказов	Логист выбирает способ доставки	Сумма доставки рассчитывается исходя из параметров всех заказов комплекта

Бизнес-процесс

[order_kit_process.bpmn] ^[2]

Бизнес-правила

• [БП-12] Комплект может содержать только заказы одного заказчика ^[2]

• [БП-13] Отгрузка части комплекта запрещена ^[2]

Системные требования

Функциональные требования

• [ФТ-11] Система должна создавать комплект из выбранных заказов одного заказчика ^[2]

• [ФТ-12] Система должна блокировать отгрузку отдельного заказа, входящего в комплект ^[2]

Требования к данным

• [ТД-3] Создание таблицы order_kits для хранения связей между заказами в комплекте ^[2]

• [ТД-4] Добавление атрибута kit_id в таблицу orders ^[2]

Требования к системным интерфейсам

• [СИ-25] POST /order-kits — создание комплекта заказов ^[2]

• [СИ-26] GET /order-kits/{id} — получение состава комплекта ^[2]

Требования к графическим интерфейсам

• [ГИ-19] Кнопка «Укомплектовать» в реестре заказов ^[2]

• [ГИ-20] Индикатор принадлежности заказа к комплекту в таблице заказов ^[2]

Нефункциональные требования

• [НФТ-5] Создание комплекта должно выполняться в одной транзакции ^[2]

• [НФТ-6] Время ответа POST /order-kits не должно превышать 2 секунд при комплекте до 50 заказов ^[2]

Итог

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

Как бы вы применили этот шаблон в своей работе: что добавили в него, отчего отказались? Будет интересно почитать идеи для улучшения.