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

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

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

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

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

• Общих принципов написания «удобных» требований
• Использования таблиц
  
• Использования схем и диаграмм
  

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

• Подход Specification by Example
• Варианты использования
• Мокапы интерфейса

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

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

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

• Используйте простой слог и слова, избегайте общих формулировок.
• Избегайте сложносочиненных предложений. В идеале, одно предложение = одна мысль.
• Если вы встречаете союзы «но», «или», то скорее всего, здесь скрыты два отдельных требования.
• Не используйте двойные отрицания.
  
• Для требованиий со структурой «если <условие>, то <результат>» пишите сначала результат, а потом - условие. Пример: «Система должна запрещать сохранение заказа, если хотя бы одного товара нет в наличии».

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

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

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

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

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

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

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

• Списки
• Абзацы
• Полужирный шрифт

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

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

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

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

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

• Заказ оплачен
• И весь товар есть в наличии на складе.

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

• Речь идет о заказе в статусе «Доставляется».
• Действие изменения статуса должно выполняться при соблюдении двух условий.

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

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

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

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

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

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

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

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

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

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

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

• Как я могу упростить эти требования?
• Как эти требования можно оформить в табличном виде?
  

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

• Таблицы воспринимаются проще, чем сплошной текст. Меньше вероятность упустить важные детали при изучении требований.
• Таблицы проще изменять и дополнять информацией в будущем (новые колонки, новые строки).
  
• Удобно добавлять комментарии (в отдельной колонке), отделяя их от требований.
  

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

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

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

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

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

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

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

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

• Тип поля.
• Значение поля при открытии формы.
• Ограничения на выбираемые данные.
• Можно ли редактировать поле и требования к валидации (если есть).

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

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

• Вы описываете два и более объектов со одинаковыми свойствами (поля формы; разделы сайта; роли пользователей и т.д.).
• Вы хотите описать реакцию системы при возникновении определенных событий.
• Вы описываете миграцию данных или маппинг полей между системами.

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

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

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

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

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

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

• Понять, с какими системами придется интегрироваться.
• Понять, какие интерфейсы ввода/вывода нужно реализовать.

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

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

• Разрабатываемая система изображается в виде круга в центре.
• По ее периметру изображаются внешние акторы (системы, пользователи, устройства) в виде прямоугольников.
• Стрелками рисуются потоки данных (в том числе физических объектов) от актора к системе и наоборот.
• Нужно показывать только основные потоки данных и/или операции.

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

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

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

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

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

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

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

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

• Start/End Events - начальное и конечное события.
  
• Activity - Действие, которое выполняет пользователь или система.
• Gates - Шлюзы. Используются для принятия решений и запуска параллельных процессов.
• Lanes - Дорожки, которые разграничивают разные типы пользователей и системы.

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

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

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

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

• У объекта много состояний (2+), логика переходов зависит от определенных событий.
• С объектом могут совершать действия сразу несколько пользователей (например, редактирование заказа). Это поможет выявить исключительные ситуации, которые можно заранее продумать, а не фиксить потом на production.
  

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

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

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