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

Какими должны быть требования

Прежде всего требования — это описания свойств и поведения системы. Вкратце именно так определяет это понятие Карл Вигерс. Но всякое ли описание системы будет являться требованием? Очевидно, что нет.

Карл Вигерс (Karl Wiegers)

Американский инженер и ИТ-консультант. Наиболее известен, как автор книги «Разработка требований к программному обеспечению» (Software Requirements), которая на текущий момент выдержала три издания (1999, 2003, 2013).

Помните известный тест про утку: если нечто ходит как утка, крякает как утка и выглядит как утка, то, вероятно, это утка и есть. Ходить как утка, крякать как утка и выглядеть как утка — это критерии, по которым мы договорились относить объекты к классу «утка».

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

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

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

Как форма влияет на качество?

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

«Плохие требования работают как скрытый налог на проект» (Карл Вигерс).

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

Завершенность (Complete)

Завершенные требования — это требования, которые содержит всю необходимую информацию, не требуя детализации и пояснений аналитика.

Какие же подходы могут способствовать обеспечению этого требования? В первую очередь, грамотно выстроенный процесс ревью и ответственные ревьюверы.

Однако, никто не застрахован от ошибок и здесь будет полезным разработать шаблоны для каждого вида проектной документации (например, шаблоны в формате Markdown для артефактов размещаемых в git или Blueprints для Confluence).

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

• описание поведения для каждого элемента UI на странице (<ссылка на шаблон>);

• макет страницы в figma (<ссылка на пример>);

• изменения в ролевую модель, обеспечивающие корректное разграничение доступа для всех групп пользователей приложения (<ссылка на пример>).

Опытный аналитик, который работает на проекте от полугода, легко сможет выявить типовые задачи в бэклоге (реализация нового метода API или интеграции, добавление новой страницы приложения, изменение роли пользователя и тому подобное) и составить для каждого типа задач отдельный чек‑лист для DoD.

Непротиворечивость (Consistent)

Критерий выполняется, если требования не противоречат другим требованиям того же типа или требованиям верхнего уровня.

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

• пользовательские и бизнес‑требования на новый модуль;

• общие функциональные и нефункциональные требования, распространяющиеся на все модули такой системы.

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

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

• добавление ссылки на элемент бэклога, который содержит связи с требованиями верхнего уровня (задачами на разработку таких требований);

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

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

• нефункциональные требования (производительность, безопасность) для API методов одного сервиса;

• функциональные требования, описывающие:

  • типовые преобразования данных при интеграциях;

  • обработку ошибок в разных частях приложения, включая условия валидации и тексты ошибок;

  • общие элементы дизайна, характерные для однотипных интерфейсов.

• и т.п.

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

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

В‑третьих, убережет коллегу‑разработчика, даже если он новичок на проекте, от написания дублирующих частей кода.

Если все еще сомневаетесь, посмотрите на требования, как на код (как предполагает подход DocsAsCode), в котором коллеги‑разработчики очень стараются не допускать копипасты, руководствуясь процедурным подходом примерно с 50-х годов прошлого века.

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

Модифицируемость (Modifiable)

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

• атомарность (единичность) — каждое требование должно выражать только одну функцию, характеристику, ограничение или качество объекта системы;

• неизбыточность — каждое требование должно быть задокументировано ровно один раз и в одном месте;

• уникальное кодирование (именование) — каждое требование или набор требований должны иметь уникальный идентификатор;

• централизованное хранение — все требования одного вида должны храниться в одной базе/ с использованием одного инструмента.

Атомарность и неизбыточность

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

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

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

Уникальное кодирование

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

Нужен ли код для каждого требования? Я считаю, что нет. Возведение принципов атомарности и кодирования в абсолют может привести к вырождению модели требований в набор коротких формулировок, промаркированных многосоставными, но мало что говорящими кодами.

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

Мой опыт показывает, что достаточно закодировать элементы структуры (например, страницы в Confluence или текстовые файлы в git), которые должны содержать множество требований, описывающих объект системы, будь то метод API, страница веб‑приложения или конфигурацию сервиса.

Централизованное хранение

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

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

Описание API сервиса должно включать следующие артефакты:

• для сервиса, в целом — спецификация OpenAPI, размещенная в репозитории (git) проекта в папке docs;

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

Прослеживаемость (Traceable)

Прослеживаемость требований (трассировка) выполняется, если для требований можно отследить как источники изменений, так и производные от требований: код, дизайн, тест-кейсы.

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

• валидация разработанного дизайна;

• код-ревью (валидация кода на соответствие функциональным и нефункциональным требованиям не заменяет тестирования, но может проводиться для критичной функциональности);

• валидация подготовленных тест-кейсов, проведение интеграционного и e2e тестирования.

Жизненный цикл продукта не останавливается при выпуске его первой версии. Если процесс разработки ведется активно, то это означает, что каждый член команды работает с несколькими версиями требований. Например, вот какие активности могут быть у аналитика в день X (см. схему ниже).

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

• разбирает ошибки в продуктивном окружении, сверяясь с требованиями для версии 1.0 продукта;

• разбирает ошибки в пред-прод. окружении и консультирует участников UAT- тестирования, руководствуясь требованиями версии 1.1 продукта;

• разбирает ошибки в тестовом окружении и консультирует QA, руководствуясь требованиями версии 1.2 продукта;

• и наконец, корректирует требования и отдельные артефакты, по замечаниям от команды.

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

Историчность изменений

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

Если для управления требованиями используется git, историчность обеспечивается базовой функциональностью этого инструмента — для корректной трассировки достаточно вливать изменения требований и кода в одну и ту же ветку репозитория (согласно GitFlow, она должна маркироваться кодом соответствующей фичи или бага).

Если часть требований ведется в Confluence или других wiki‑движках, помимо сохранения промежуточных версий необходимо вести маркировку этих требований. Например, добавить для каждой страницы с требованиями раздел с историей изменений.

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

• инкремент мажорной версии, если сделаны несовместимые изменения;

• минорной, если совместимые;

• патч‑версии, если изменения носят косметический характер (не требуют усилий по разработке).

Заключение

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

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

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