Опыт структурирования спецификации требований для разработчиков

Из практики системного аналитика

Радзишевский А. О.

Введение

Получить бы медаль, а уж с обратной ее стороной найдем, что делать.
(Георгий Александров)

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

Во многих работах, посвященных управлению требованиями, авторы акцентируют внимание на том, как максимально полно и качественно формализовать потребности заказчика [1][2][3]. В этой статье рассматривается несколько иной взгляд на качество требований — качество требований глазами команды: разработчиков, тестировщиков, руководителей проектов. Ведь именно эти люди и являются основными потребителями работы аналитика. И от того насколько точно созданные спецификации соответствуют их задачам, зависит качество и конечная себестоимость этого продукта.

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

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

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

В начале своей карьеры я работал программистом, потом руководителем группы разработки, но через 18 лет просто кодировать мне стало не интересно и я решил изменить вид своей деятельности, окунувшись в сферу системного анализа и управления проектами. На этом поприще я и тружусь последние 8 лет.

Работая во всех трех ипостасях в разных софтверных компаниях, я не раз наблюдал перекосы приоритетов в этом триумвирате. Я работал в команде, где должности системного аналитика не было вообще и его роль “растекалась” между программистами. Я работал в команде, где системный аналитик был ее руководителем и программисты страдали от излишнего «погружения» в несущественные, с их точки зрения, детали предметной области. Была в моей практике команда, руководитель которой слабо себе представлял содержание работы и аналитиков, и разработчиков. Ему было важно продать продукт, поэтому каждый “варился в своей тарелке”. Вывод, который я сделал из своего опыта состоит в том, что  в команде, разрабатывающей ПО, есть здоровый конфликт интересов, как минимум, между группой аналитиков, группой разработчиков и руководителем проект. И как любой конфликт он может быть использован для постоянного улучшения качества процесса создания ПО.

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

Основной круг заинтересованных лиц в таких командах и их потребности:

  1. Разработчики. Это главные потребители спецификаций требований. Для них важно насколько быстро и точно они смогут воспринять спецификацию, чтобы преобразовать требования в программный код.
  2. Руководитель проекта. Для него важно насколько удобно он сможет «нарезать» спецификации на атомарные задачи для остальных членов команды. Атомарные задачи, должны с одной стороны являться четким, однозначным заданием исполнителю, а с другой — быть прогнозируемым мерилом использования ресурсов для составления детального плана проекта.
  3. Тестировщики. Это специалисты, обеспечивающие качество продукта. Для них важно насколько удобно им будет формировать по требованиям сценарии тестирования, карты приемки и т.д.

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

Для того чтобы изложение материала сделать более наглядным в статью включены фрагменты спецификаций требований проекта: «Автоматизация процесса «управление требованиями»».

Состав документа «Спецификация требований»

За некачественные требования всегда расплачивается заказчик.
Иногда сразу, иногда в рассрочку.

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

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

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

ill1

Рисунок 1. Компонентная модель Целевой системы.

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

  1. Сущности предметной области;
  2. Интерфейс пользователя;
  3. Процедуры, связанные с событиями интерфейса пользователя;
  4. Вспомогательные процессы;
  5. Периодические задания;
  6. Шаблоны отчетов;
  7. Права доступа;

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

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

Порядок представления в документе этих разделов зависит от последовательности этапов разработки. Пример последовательности этапов разработки для рассматриваемого класса систем приведен на Рисунке 2:

ill1

Рисунок 2. Модель варианта основного процесса создания ПО.

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

Последовательность разделов спецификации требований и их наполнение

Итак, с чего может начинаться знакомство команды разработки с требованиями? Хорошим тоном будет включение в начало документа раздела с обзором его структуры и представления информации, а также разъяснением, как правильно ее использовать.

Пример обзора документа:

example1

Для лучшего восприятия контекста разрабатываемой системы, помимо разделов, определенных в структуре документа как обязательные, я стараюсь включить в текст информацию, предназначенную для знакомства разработчиков с целями, которые должны быть достигнуты в результате разработки целевого продукта или его составного модуля. Разработчики должны осознавать, что хочет получить заказчик на выходе проекта. Для описания этого раздела подойдут формализованные Потребности заказчика. Похожий раздел есть в большинстве стандартов, например в ГОСТ-34.602-89  [4] он называется «назначение и цели создания (развития) системы».

Ниже приведен пример описания Потребностей:

example2

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

Для комфортного «погружения» в требования, разработчику необходимо с самого начала представлять себе всю систему целиком. Поэтому в начало документа необходимо добавить раздел, описывающий общую компонентную архитектуру продукта все основные компоненты и описание способов их взаимодействия. В своей работе «Унифицированный процесс разработки ПО» [5] Айвар Якобсон термину Архитектура дал такое определение: «это представление всего проекта с выделением важных характеристик и затушевыванием деталей» .

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

Ниже приведен пример включения в требования описания архитектуры системы.example3example4

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

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

Когда мы представили общие потребности заказчика и визуализировали архитектуру разрабатываемого продукта, читатель уже имеет представление о его основных функциях и структуре построения системы в целом. Теперь можно перейти к более детальному знакомству с основными сценариями ее использования. В ГОСТ-34.602-89 [4] подобный раздел называется «требования к функциям (задачам), выполняемым системой». 

Часто при оформлении подобных разделов  используют диаграммы: Вариантов использования (UseCase), описания Бизнес-процессов (BPMN),  алгоритмов выполнения (Activity), функциональных моделей IDEF0 и т.д. Все эти виды диаграмм незаменимы на этапе проектирования, определения рамок проекта и т.п. Но по моему опыту они малоприменимы для программистов. Разработчикам гораздо комфортнее работать именно со сценариями использования системы в виде структурированного текстового описания.

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

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

  • Участники, работающие с описанием, не имеют специальной подготовки и не могут свободно читать нотации;
  • Читатели по описанию должны четко и полно представить себе все действия, которые будут выполняться пользователями при помощи целевого продукта;
  • Необходимо структурировать и представить информацию, используя приемы лучших практик описания процессов;

Ниже приведен пример фрагмента описания сценария использования системы:example5example6

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

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

Состав и форма спецификации требований

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

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

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

Ниже приведен пример спецификаций для рассматриваемого проекта:

example7example8example9

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

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

Похожий раздел есть в ГОСТ-34.602-89 [4] и называется он «Описание организации информационной базы».

После описания всех Сущностей, которые необходимо реализовать в данном модуле, можно приступать к разработке визуальных форм. Требования к формам удобно оформлять в таком же стиле. При описании важно опираться на визуальные компоненты, предоставляемые платформой, в которой ведется разработка.

example10example11

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

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

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

Если в модуле используются сложные функции, предполагающие описание объемных алгоритмов, определение входящих и выходящих параметров, разработку дополнительной структуры хранения данных и т.д., то я включаю в документ отдельный раздел с требованиями к вспомогательным функциям. На него могут ссылаться спецификации, описывающие действия для форм, рассмотренные выше. Например, вспомогательную функцию удобно использовать, когда одна и та же базовая функция вызывается при событиях разных форм. Похожий раздел есть в ГОСТ-34.602-89 [4] и называется «Описание алгоритма».

Ниже приведен пример подобного представления:

example13

Дальше в документе могут следовать разделы об: Отчетах, Периодических заданиях, Расширенном поиске и т.п. Эти пункты желательно заполнять с таким же уровнем детализации, как показано выше в примерах.

Еще один немаловажный раздел, который должен быть упомянут в документе для подобного рода систем, посвящен правам доступа. В нем идентифицируются Роли, приводится их описание, а также определяются права доступа для этих ролей к объектам данных и элементам интерфейса пользователя. Похожий подраздел есть например в ГОСТ-34.602-89 [4] и называется «требования к защите информации от несанкционированного доступа».

Ниже приведен пример требований к подсистеме управления правами доступа:

example14example15example16

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

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

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

Для более точного расчета можно использовать коэффициенты сложности для реализуемых объектов. Например: «сложная форма» — 1,5; «обычная форма» — 1; «простая форма» — 0,5. Каждый тип элемента должен иметь свои значения.

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

example17

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

ill4

Рисунок 3. Фрагмент плана-графика проекта

Заключение

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

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

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

Радзишевский А. О. Опыт структурирования спецификации требований для разработчиков. //Практика проектирования систем.-2016. [электронный ресурс] — Режим доступа: http://reqcenter.pro/req-spec/, свободный. — Загл. с экрана

Литература

[1] К. И. Вигерс, «Разработка требований к программному обеспечению», Издательско-торговый дом «Русская Редакция», 2004, p. 576.
[2] А. Коберн, «Современные методы описания функциональных требований», Лори, 2002, p. 288.
[3] У. Д. Леффингуэлл Дин, «Принципы работы с требованиями к ПО», Вильямс, 2002, p. 448.
[4] ГОСТ 34.602-89 «Информационная технология. Комплекс стандартов на автоматизированные системы. Техническое задание на создание автоматизированной системы».
[5] Б. Г. Р. Д. Якобсон А., «Унифицированный процесс разработки программного обеспечения», Питер, 2002, p. 496.
[6] AnyaNartova. Общий обзор моделей Sybase PowerDesigner. //sql.ru [электронный ресурс] — Режим доступа: http://www.sql.ru/blogs/sybase/945, свободный. — Загл. с экрана
[7] Леоненков А. Самоучитель UML. www.e-reading.club [электронный ресурс] — Режим доступа: http://www.e-reading.club/book.php?book=33640, свободный. — Загл. с экрана