Как писать требования чтобы их понимали

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

Данный материал будет интересен бизнес- и системным аналитикам, менеджерам и владельцам продуктов, CEO небольших стартапов, в общем - всем, кому нужно писать требования к разработке фичей и ИТ-систем.

Здесь не будет базовой теории, что есть требование и что оно должно соответствовать SMART (надеюсь, вы это и так знаете). Скорее, я покажу некие best practice, как требования лучше оформлять в документации.

Начнем с обсуждения:

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

Требования это не роман и удивлять слогом тут никого не нужно. Я еще не раз это повторю в статье, но тот кто читает ваши требования, должен напрягаться по минимуму.

Здесь, как и в дизайне интерфейсов, отлично работает правило: «Не заставляйте меня думать», про которое писал Стив Круг в одноименной книге.

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

Исходное требование:

«Должна быть возможность удалить конкретный товар или сразу все товары из корзины».

По сути, данное требование содержит два отдельных требования:

Такое разделение поможет не пропустить скрытое требование разработчику или QA и подскажет менеджеру, что здесь лучше завести две отдельные задачи.

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

Используйте средства, которые доступны вам в любом редакторе:

Например, если вы используете союз «и» (или несколько таких союзов), то лучше каждое условие написать с новой строки.

Исходное требование:

«Необходимо перевести заказ в статус «Доставляется», если заказ оплачен и весь товар есть в наличии на складе.»

Давайте упростим восприятие этого требования. Получим следующее:

«Необходимо перевести заказ в статус «Доставляется», если:

Что мы сделали? Мы сняли часть когнитивной нагрузки с того, кто будет изучать данное требование. Уже из форматирования становится видно, что:

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

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

Исходное требование:

«Заказ отображается в личном кабинете пользователя, если заказ находится в одном из статусов: «Новый», «Ожидает оплаты», «Оплачен», «Доставляется». Заказ в статусе «Доставлен» не должен отображаться в личном кабинете.»

Как можно его упростить:

«Заказ отображается в личном кабинете пользователя, если его статус не равен «Доставлен».

Во-первых, мы сделали само требование короче, а значит вероятность, что его прочитают стала выше.

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

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

Запомните, таблицы - ваш главный «бро» 🙂

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

Почему таблицы лучше работают:

Рассмотрим пример части из ТЗ на большую государственную систему из открытых источников:

«Успешно авторизованный пользователь, входящий в группу пользователей c ролью «Исполнитель», должен попадать на «UI-006 Главная страница личного кабинета», а пользователь, входящий в группу пользователей с ролью «Наблюдатель» – на «UI-092 Главная страница Мониторинга (дашборд)» подсистемы «Мониторинг». Если пользователь в личном кабинете настроил страницу по умолчанию, то открываемая страница должна определяться на основе выбранной настройки.»

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

«После успешной авторизации в системе, пользователю должна открываться стартовая страница, согласно условиям ниже:»

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

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

Пример формы редактирования из того же ТЗ:

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

Для описания действий на форме (Сохранить и Отмена) лучше использовать отдельную таблицу, так как описания действий и полей формы сильно отличаются.

Когда использовать таблицы (спойлер - всегда!):

Схемы и диаграммы - это еще один отличный способ улучшить качество передачи знаний в команде разработки.

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

Далее я поделюсь схемами, которые использую чаще всего.

Зачем нужна: Показывает как разрабатываемая система взаимодействует с внешними миром.

Внешний мир может быть представлен: другими ИТ-системами, пользователями или устройствами.

Когда использовать: На этапе проектирования системы, чтобы:

P.S. Еще эту диаграмму очень любят архитекторы.

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

Пример контекстной диаграммы из книги «Разработка требований к программному обеспечению» (Джой Битти, Карл Вигерс):

BPMN - это нотация описания бизнес-процессов в виде набора обозначений и ряда определенных правил.

Зачем нужна: Позволяет зафиксировать описание бизнес-процессов на этапе их дизайна и использовать это «знание» на этапе разработки и внедрения решения.

Когда использовать: Вообще, у BPMN довольно широкий спектр применения.

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

При разработке BPMN-диаграмм (в контексте описания требований) главное - избавиться от перфекционизма.

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

Качество ваших диаграмм будет зависеть от количества ранее созданных (волшебной пилюли, увы, здесь нет). На начальных этапах советую использовать базовые элементы:

Пример описания бизнес-процесса обработки инцидентов:

Если вам интересна отдельная статья про примеры построения BPMN-диаграмм на реальных примерах, напишите об этом в комментариях.

Зачем нужна: показывает как объект переходит из одного состояния в другое.

Когда использовать:

Как и схемы в BPMN, диаграмма состояний отлично читается и техническими специалистами, и бизнес-пользователями, и экспертами.

Пример диаграммы состояний для объекта «инцидент» из BPMN-диаграммы выше:

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