Шаблон написания спецификации к ПО

Шаблон написания технической спецификации к разработке программного обеспечения (ПО)

Шаблон спецификации требований

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

Скачать шаблон

Приведенный шаблон подходит для многих проектов. Состоит он из следующих разделов:

1. Введение
1.1 Назначение
1.2 Соглашения, принятые в документах
1.3 Границы проекта
1.4 Ссылки
2. Общее описание
2.1 Общий взгляд на продукт
2.2 Классы и характеристики пользователей
2.3 Операционная среда
2.4 Ограничения дизайна и реализации
2.5 Предположения и зависимости
3. Функции системы
3.x Функция системы X
3.x.1 Описание
3.x.2 Функциональные требования
4. Требования к данным
4.1 Логическая модель данных
4.2 Словарь данных
4.3 Отчеты
4.4 Получение, целостность, хранение и утилизация данных
5. Требования к внешним интерфейсам
5.1 Пользовательские интерфейсы
5.2 Интерфейсы ПО
5.3 Интерфейсы оборудования
5.4 Коммуникационные интерфейсы
6. Атрибуты качества
6.1 Удобство использования
6.2 Производительность
6.3 Безопасность
6.4 Техника безопасности
6.x [Другие]
7. Требования по интернационализации и локализации
8. Остальные требования
Приложение A. Словарь терминов
Приложение Б. Модели анализа

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

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

Описание разделов шаблона спецификации требований

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

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

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

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

1.4 Ссылки
Перечислите все документы или другие ресурсы, на которые вы ссылаетесь в этой спецификации, в том числе гиперссылки на них, если их местоположение меняться не будет. Это могут быть руководства по стилям пользовательского интерфейса, контракты, стандарты, спецификации к системным требованиям, спецификации интерфейса и спецификации требований к ПО связанных продуктов. Объем информации должен быть достаточным для того, чтобы пользователь сумел при необходимости получить доступ к каждому указанному материалу, а именно: название, имя автора, номер версии, дата, источник, место хранения или URL-адрес.

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

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

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

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

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

2.5 Предположения и зависимости
Предположение (assumption) — это утверждение, которое предполагается верным в отсутствие знаний или доказательств иного. Проблемы возможны в том случае, если предположение неверны, устарели, не находятся в совместном использовании или изменяются, поэтому определенные предположения можно отнести к группе рисков проекта. Один читатель спецификации требований к ПО может считать, что продукт будут соответствовать особому стандарту пользовательского интерфейса, тогда как другой предположит нечто совершенно иное. Разработчик может думать, что определенный набор функций написан специально для этого приложения, бизнес-аналитик — что он будет взят из предыдущего проекта, а менеджер проекта — что предполагается приобрести коммерческую библиотеку функций. Включаемые здесь предположения относятся к системной функциональности; предположения относящиеся к бизнесу представлены в документе концепции и границ проекта. Определите все зависимости проекта или создаваемой системы от внешних факторов или компонентов вне ее контроля. Например, до установки продукта может требоваться установить Microsoft .NET Framework 4.5 или более позднюю версию — это зависимость.

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

3.x Функция системы X
Опишите название особенности несколькими словами, например «3.1 Проверка правописания». Так же назовите подразделы с 3.x.1 по 3.x.3 для каждой функции системы.

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

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

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

4.1 Логическая модель данных
Модель данных это визуальное представление объектов и наборов данных, которые будет обрабатывать система, а также отношений между ними. Существует много видов нотации для моделирования данных, в том числе диаграммы отношений «сущность–связь» и диаграммы классов UML. Можно включить модель данных для бизнес-операций, выполняемых системой или логическое представление данных, с которыми будет работать система. Это не то же самое, что модель данных реализации, которая реализуется в виде дизайна базы данных.

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

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

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

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

Войны интерфейсов
Две команды разработчиков ПО объединились для создания флагманского продукта компании A. Datum Corporation. Команда, отвечающая за базу знаний, создала сложное ядро анализа на C++, а команда, отвечающая за приложения, реализовала пользовательский интерфейс на Java. Подсистемы взаимодействовали между собой посредством API. К сожалению, команда, отвечающая за базу знаний, периодически модифицировала API, в результате чего систему не удавалось собрать и запустить на выполнение должным образом. Команде, отвечающей за приложения, требовалось несколько часов, чтобы распознать все проблемы и определить основную причину — изменение API. Эти изменения не согласовывались, не доводились до сведения всех заинтересованных в проекте лиц и не были скоординированы с соответствующими модификациями в коде на Java. Изменение интерфейса обязательно требует уведомления об этом людей, группы или системы на другой стороне этого интерфейса. Интерфейс скрепляет компоненты вашей системы — включая пользователей, поэтому необходимо документировать детали интерфейса и синхронизировать модификации в процессе управления изменениями в проекте.

5.1 Пользовательские интерфейсы
Опишите логические характеристики каждого пользовательского интерфейса, который необходим системе. Некоторые особенные характеристики пользовательских интерфейсов могут упоминаться в разделе «6.1 Удобство использования». Некоторые из них перечислены здесь:
• ссылки на стандарты графического интерфейса пользователей или стилевые рекомендации для семейства продуктов, которые необходимо соблюдать;
• стандарты шрифтов, значков, названий кнопок, изображений, цветовых схем, последовательностей полей вкладок, часто используемых элементов управления, графики фирменного стиля, уведомления о зарегистрированных товарных знаках и о конфиденциальности и т.п.;
• размер и конфигурация экрана или ограничения разрешения;
• стандартные кнопки, функции или ссылки перемещения, одинаковые для всех экранов, например кнопка справки;
• сочетания клавиш;
• стандарты отображения и текста сообщений;
• стандарты проверки данных (такие как ограничения на вводимые значения и когда нужно проверять содержимое полей);
• стандарты конфигурации интерфейса для упрощения локализации ПО;
• специальные возможности для пользователей с проблемами со зрением, различением цвета и другими ограничениями.

5.2 Интерфейсы ПО
Опишите связи продукта и других компонентов ПО (идентифицированные по имени и версии), в том числе другие приложения, базы данных, операционные системы, средства, библиотеки, веб-сайты и интегрированные серийные компоненты. Укажите назначение, форматы и содержимое сообщений, данных и контрольных значений, обмен которыми происходит между компонентами ПО. Опишите соответствия между входными и выходными данными между системами и все преобразования, которые должны происходить с данными при перемещении между системами. Опишите службы, необходимые внешним компонентам ПО, и природу взаимодействия между компонентами. Определите данные, которыми будут обмениваться и к которым будут иметь общий доступ компоненты ПО. Определите нефункциональные требования, влияющие на интерфейс, такие как уровни обслуживания для времени и частоты отклика или меры и ограничения безопасности. Часть этой информации может быть определена как требования к данным в разделе 4 или как требования к взаимодействию в разделе «6. Атрибуты качества».

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

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

6. Атрибуты качества
В этом разделе описываются нефункциональные требования помимо ограничений, описанных в разделе 2.4, и требований к внешним интерфейсам, описанным в разделе 5. Эти характеристики должны быть точно определены и поддаваться проверке и измерению. Укажите относительные приоритеты различных атрибутов, например приоритет простоты использования над легкостью изучения или приоритет безопасности над производительностью. Необходимые степени качества удается гораздо эффективнее описать с помощью подробных нотаций спецификации, таких, как Planguage, чем с помощью простых описательных утверждений.

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

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

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

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

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

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

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

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

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

Данный шаблон призван помочь, в том числе, и для приемки работ. Вы всегда можете заказать разработку ТЗ у нас.

Не забудьте оставить свои комментарии и практики ниже!

Posted in Аналитика and tagged , , , .
  • Владимир

    проверка работы disqus