1. Что такое ЕСПД?

ЕСПД (Единая система программной документации) – это комплекс государственных стандартов СССР (и РФ), устанавливающих единые взаимосвязанные правила разработки, оформления и ведения программной документацииru.wikipedia.org. Проще говоря, ЕСПД – это стандартная система документации для программных средств, аналогичная тому, как ЕСКД (Единая система конструкторской документации) регламентирует документацию на оборудование и чертежи. ЕСПД была разработана в 1970–80-х годах и охватывает практически все виды документов, создаваемых при разработке программного обеспечения (ПО). Цель ЕСПД – унифицировать и систематизировать документацию по программам, чтобы разные организации говорили на одном «документальном языке» и соблюдали единые требования.

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

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

• снизить трудоемкость и повысить эффективность разработки и сопровождения программных изделий;

• облегчить автоматизацию создания и хранения программной документацииru.wikipedia.org.

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

Однако у ЕСПД есть и недостатки. Стандарты создавались в эпоху каскадной (waterfall) модели разработки и ориентированы на нееstudfile.net. В них мало внимания уделено документированию качественных атрибутов (например, надёжности, удобства использования) и отсутствуют современные форматы (например, встроенные справки, интерактивная документация). Также ЕСПД слабо связана с другими системами стандартов (например, с ЕСКД по оформлению технической документации на оборудование)studfile.net. Нет рекомендаций по самодокументированию ПО (например, системам контекстной помощи, online-help) или по учету методологий, появившихся позже (agile, гибкая документация)studfile.net. Тем не менее, ЕСПД по-прежнему дает базовое представление о том, какая документация нужна при классической разработке ПО.

Статус и современное применение: Сегодня стандарты ЕСПД носят рекомендательный характерru.wikipedia.org. Их использование не является обязательным по закону, но может требоваться в рамках конкретного договора или проекта. На практике ЕСПД применяют там, где нужна формальная документация по государственным или отраслевым требованиям:

• Госзакупки и госконтракты: В технических заданиях на государственные проекты часто прямо указывают, что документация должна соответствовать ГОСТ 19 (ЕСПД). В таких случаях стандарты становятся обязательными к выполнению на контрактной основеru.wikipedia.org.

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

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

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

Важно понимать, что ЕСПД – не единственная система документации. Существуют также стандарты комплекса ГОСТ 34 (для автоматизированных систем) и международные стандарты (ISO/IEC/IEEE 12207, 15289 и др.), но в контексте учебной программы МДК.01.02 нас интересует именно отечественная система ЕСПД как базовый подход.

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

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

2. Виды документов по ЕСПД

Стандарты серии ГОСТ 19 (ЕСПД) определяют полный перечень документов, которые могут создаваться при работе над программным обеспечениемru.wikipedia.orgru.wikipedia.org. Ниже перечислены основные виды программных документов по ЕСПД, наиболее важные для понимания процесса документирования. Для каждого документа указано его назначение. (Всего стандартами предусмотрено более десятка типов документов, но мы рассмотрим основные, наиболее часто встречающиеся.)

2.1. Техническое задание (ТЗ)

Техническое задание – один из главных документов в ЕСПД. Это формализованное описание того, чтодолжно быть разработано и с какими требованиями. ТЗ определяет назначение и область применения будущей программы, содержит все основные требования (функциональные, технические, экономические, специальные), а также оговаривает этапы разработки и виды испытанийtechwrconsult.com. Проще говоря, ТЗ – это контракт между заказчиком и разработчиком на разработку ПО.

Ключевые моменты, отражаемые в ТЗ по ГОСТ 19.201-78:

• Введение: общие сведения – наименование программы и краткая область применения.

• Основания для разработки: на основании какого документа или решения начата разработка, кем утверждено.

• Назначение разработки: для чего создается программа, какую задачу решает, сфера применения.

• Требования к программе: все требования к функционалу, производительности, надежности, интерфейсу, совместимости и др. (в том числе:

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

  • требования к надежности (на отказоустойчивость, безопасность);

  • условия эксплуатации (окружение, климатические или аппаратные ограничения);

  • требования к техническим средствам (минимальная конфигурация оборудования);

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

  • специальные требования (например, требования к защите информации) ).

• Технико-экономические показатели: ожидаемые показатели эффективности (например, экономия ресурсов, допустимое время отклика и т.п.), если применимо.

• Стадии и этапы разработки: план проекта – какие фазы будут (эскизный проект, рабочий проект, испытания и т.д.) и в какие сроки.

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

• Приложения: дополнительные материалы – может включать чертежи, схемы алгоритмов, протоколы и др.

По ГОСТ ТЗ обязательно содержит перечисленные разделы (их формулировки стандартизованы)techwrconsult.comtechwrconsult.com. Благодаря этому ТЗ по ГОСТ выглядит очень структурированно и четко. Например, в разделе требований к программе в ТЗ для информационной системы может быть записано: «Программа должна обеспечивать хранение не менее 1 млн записей в базе данных и одновременную работу не менее 100 пользователей» – это функциональное требование. Также там будут требования к надежности: «Время восстановления работы системы после отказа – не более 1 часа», требования к совместимости: «Система должна поддерживать импорт данных из формата CSV»и т.д.

Важно, что ТЗ описывает что нужно сделать, но не как. Студенты часто путают цель и средство: в ТЗ указываются требуемые характеристики и функции продукта, а не способы их реализации. Например, правильно: «Приложение должно обеспечивать авторизацию пользователей через двухфакторную аутентификацию». Неправильно для ТЗ: «Настроить Firebase Auth и SMS-шлюз для двухфакторной аутентификации» – это уже деталь реализации, которая не должна быть в требованиях.

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

2.2. Описание программы (ОП)

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

По ГОСТ 19.402-78, описание программы включает:

• общие сведения о программе (название, версия, назначение – кратко);

• логическую структуру: из каких основных частей (модулей, компонентов) состоит программа и как они взаимодействуют;

• описание важных алгоритмов или принципов работы (например, схема обработки данных, принципы расчета);

• возможно, отличительные особенности реализации.

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

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

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

2.3. Программа и методика испытаний (ПМИ)

Программа и методика испытаний – документ, в котором описано что и как тестировать в разработанной программе. Согласно ГОСТ 19.301-79, ПМИ содержит перечень требований, подлежащих проверке при испытании программы, и описывает порядок и методы проверки каждого требованияtechwrconsult.com. Проще говоря, это план испытаний и методика их проведения.

Стандартом предусмотрены разделы ПМИ:

• Объект испытаний: что именно испытывается (наименование программы, версия).

• Цель испытаний: что мы хотим подтвердить испытаниями (например, соответствие программы ТЗ, стабильность работы и т.п.)techwrconsult.com.

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

• Требования к программной документации: проверка того, что вся необходимая документация подготовлена (например, наличие руководства пользователя, соответствие документации требованиям ТЗ)techwrconsult.com. Это интересный раздел – он гарантирует, что проверяется не только сама программа, но и комплект документов к ней.

• Средства и порядок испытаний: какие необходимы инструменты, окружение для тестирования (технические и программные средства), и как организован процесс испытанийtechwrconsult.com. Например, указывается, что испытания проводятся на таком-то оборудовании, с помощью таких-то тестовых средств; порядок – сначала выполняются такие-то тесты, затем такие-то.

• Методы испытаний: описание методик, по которым проводятся проверкиtechwrconsult.com. Здесь перечисляется, каким образом проверяется каждое требование. Часто этот раздел содержит таблицу или перечень тестовых случаев: для каждого проверяемого требования – метод (например: «Требование 3.5.1: проверка методом функционального тестирования, ввод граничных значений… ожидаемый результат …»). Рекомендуется располагать методы испытаний в том же порядке, что и требования, чтобы легко проследить трассировкуtechwrconsult.com.

• Приложения: могут включать конкретные тестовые данные, примеры входных/выходных файлов, распечатки результатов тестов, скриншоты и т.п.techwrconsult.com – все, что подтверждает факт проведения испытаний и их результаты.

Проще говоря, ПМИ – это тест-план и тест-спецификация в одном документе, оформленные по ГОСТ. Например, для мобильного приложения «Банк Онлайн» ПМИ будет содержать: – перечень проверяемых функций (вход в систему, просмотр баланса, перевод средств, оплата услуг и т.д., соответствующих требованиям ТЗ), – методы проверки (например, для функции «перевод средств» метод испытаний: создать два счета, выполнить перевод, убедиться, что балансы изменились правильно, проверить сообщения об ошибках при недостаточных средствах и т.п.), – указание, что необходимо для тестов (тестовый стенд с определенными параметрами, тестовые учетные записи и данные), – и, возможно, таблицу с результатами (прошел/не прошел).

Для учебных целей ПМИ можно сравнить с современным тест-планом и чек-листом. Этот документ особенно важен для финальной стадии – приемочных испытаний. Обычно ПМИ составляется перед началом тестирования, затем по нему проводят испытания, и на основе ПМИ готовят протокол испытаний. В протокол записывают, какие тесты пройдены, какие нет, какие замечания. Но протокол – отдельный документ (в ЕСПД он может оформляться как часть акта или отчета о приемке).

2.4. Руководство оператора (пользователя)

Руководство оператора (в некоторых проектах его могут называть руководством пользователя) – документ, предназначенный для конечного пользователя программы, то есть того, кто будет с ней работать. Согласно ГОСТ 19.505-79, руководство оператора должно содержать сведения, необходимые для того, чтобы оператор (пользователь) мог успешно выполнять свои задачи с помощью программыtechwrconsult.com. Проще говоря, это пользовательская инструкция к программному продукту.

Стандартная структура руководства оператора включает разделы:

• Назначение программы: для чего предназначено ПО, какие основные функции оно выполняетrobot.bmstu.ru.

• Условия выполнения программы: на каком оборудовании и программном окружении она работает, требования к ресурсам. Например, поддерживаемые операционные системы, необходимый объём памяти, требования к наличию интернета и т.д.robot.bmstu.ru. Здесь же могут быть указаны права доступа (какой уровень пользователя нужен) или роль оператора.

• Выполнение программы (порядок работы): пошаговое описание, как пользоваться программойrobot.bmstu.ru. Это сердцевина руководства пользователя: описываются все основные операции, интерфейс, меню, команды. По сути, этот раздел учит пользователя, как выполнять нужные действия. Например, для приложения: как установить программу, как запустить, как выполнить ту или иную операцию. Может быть разделено на подразделы по функциям (например, «Добавление нового документа», «Настройка параметров», «Просмотр отчетов» – каждый со своим описанием).

• Сообщения оператору: описание всех сообщений и предупреждений, которые программа выдает пользователю, и действия при этих сообщенияхrobot.bmstu.ru. Например, если появляется ошибка с кодом или текстом, руководство должно объяснять, что она означает и что делать. Также сюда относят инструкции по действию в нештатных ситуациях (например: «Если программа зависла, то…», «Если вы получили сообщение о потере связи, попробуйте… »).

Дополнительно руководство оператора может включать:

• Установку и настройку программы: если пользователь сам должен устанавливать ПО, приводятся инструкции по установке, требования к системе, настройке параметров.

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

• Справочные сведения: горячие клавиши, форматы файлов, ограничение на ввод (например, «пароль должен содержать 8 символов» – подобные сведения тоже могут быть здесь).

• Глоссарий или список условных обозначений: если в интерфейсе используются специальные термины или сокращения, их объясняют.

Пример: Руководство пользователя для приложения «Telegram» будет содержать описание интерфейса (что такое список чатов, что значат иконки), инструкцию как отправить сообщение, как прикрепить файл, как создать групповой чат, как настроить уведомления, и т.п. Также будет перечисление возможных сообщений (например, «Ошибка: не удалось подключиться к интернету» – объяснение, что проблема с сетью, попробуйте подключиться к Wi-Fi). Таким образом, любой новый пользователь, прочитав руководство, должен суметь установить приложение и выполнить основные действия.

Руководство оператора – эксплуатационный документ, его пишет обычно технический писатель или разработчик, ориентируясь на неподготовленного читателя. Язык документа должен быть понятным, без избыточных технических деталей (в отличие от руководства программиста, о котором далее). Важно соблюдение структуры и полноты: пользователь не должен остаться с вопросом «что делать, если …?».

2.5. Руководство программиста

Руководство программиста – документ, предназначенный для специалистов-программистов, которые будут заниматься сопровождением, доработкой или интеграцией данного программного средства. В ГОСТ 19.504-79 указано, что руководство программиста содержит сведения, необходимые для эксплуатации программы (в техническом смысле)techwrconsult.com. Здесь под «эксплуатацией» понимается именно использование программы в вычислительной среде, возможно, ее адаптация, настройка, встраивание в другие комплексы.

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

Типичные разделы руководства программиста:

• Назначение и условия применения программы: чем программа полезна с точки зрения программиста, где может применяться, на каких условиях (какое окружение, какие требования к системе, к квалификации персонала)asutpseta.narod.ru.

• Характеристика программы: основные технические характеристики – объем, требуемые ресурсы, производительность, особенности (например, «программа поддерживает работу в многопоточной среде», «использует базу данных PostgreSQL», и т.п.). Здесь же описываются встроенные средства обеспечения корректности (например, система логирования, самодиагностика)asutpseta.narod.ru.

• Обращение к программе: как запустить программу, как вызывать ее функции. Например, если это библиотека – как подключить и вызвать функции API; если это сервис – как обращаться к его интерфейсам (команды, запросы)asutpseta.narod.ru.

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

• Входные и выходные данные: описание форматов данных, с которыми работает программа, интерфейсов обмена данными. Например, формат конфигурационного файла, структура входного файла, формат выходного отчета, API (сигнатуры функций, endpoints REST API и т.д.)asutpseta.narod.ru.

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

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

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

Проще говоря, руководство программиста – это документация для разработчика о разработке. Например, существует большое количество open-source библиотек, у которых есть “Developer’s Guide” – вот аналог руководства программиста. Он учит: «чтобы использовать нашу библиотеку, импортируйте такой-то пакет, вызовите такие-то функции; перед запуском установите переменные окружения…; если хотите расширить функциональность, реализуйте интерфейс X и поместите его в каталог плагинов…» и т.п.

Если взять прикладной пример: предположим, разработано ПО «Система обработки заявок», которое может встраиваться в инфраструктуру предприятия и дорабатываться. Руководство программиста к ней будет содержать:

• Описание архитектуры системы с технической точки зрения (например, «веб-приложение на Java, использует Spring Framework, БД Oracle, кэш Redis»);

• Способ деплоя (развертывания) на сервере, настройки конфигурационных файлов (URL базы данных, учетные данные, настройки логирования);

• Описание API интеграции (например, «для интеграции с внешними системами предусмотрен REST API: список методов… формат JSON сообщений…»);

• Описание структуры исходного кода, если система поставляется с исходниками, и рекомендации, как вносить изменения;

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

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

Обратите внимание, что руководство программиста ≠ комментарии в коде. Это отдельный документ, обобщающий важные технические моменты. Комментарии в коде – тоже форма документации (самодокументирование), но ГОСТ рассматривает именно отдельный документ.

2.6. Ведомость эксплуатационных документов

Ведомость эксплуатационных документов – это документ-список, своего рода опись всех эксплуатационных документов, относящихся к программеtechwrconsult.com. Под эксплуатационными документами в ЕСПД понимаются документы, предназначенные для обеспечения функционирования программы у пользователя. К ним относят уже упомянутые руководства (пользователя, программиста, системного программиста), описание применения, формуляр, руководство по техническому обслуживанию и т.д.

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

• Все наименования эксплуатационных документов, подготовленных для данной программы.

• Их обозначения (документы по ГОСТ нумеруются).

• Возможно, информация о том, где (в каком томе, книге) они находятся.

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

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

1. Руководство оператора (обозначение документа, например, «АО-ХХХХ.34.605-2025 Рук. оператора»).

2. Руководство программиста …

3. Формуляр …

4. Программа и методика испытаний … (хотя ПМИ – не эксплуатационный, а приемо-сдаточный документ, его могут включать в комплект поставки по требованию).

5. … и т.д.

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

2.7. Формуляр программы

Формуляр – интересный вид документа из ЕСПД, фактически “паспорт” программы. В формуляре указываются основные технические характеристики программы, комплектация и сведения об ее эксплуатацииtechwrconsult.com. Этот документ схож по идее с паспортом на прибор или техническое изделие.

Что обычно входит в формуляр:

• Основные характеристики программы: например, версия программы, объём занимаемой памяти, требования к оборудованию, допустимая нагрузка (количество одновременных пользователей), язык программирования, дата выпуска версии, разработчики. Все количественные и однозначные параметры программы фиксируются в формуляре.

• Комплектность программы: перечень того, что поставляется с программой. Здесь же может повторяться список документов (перекрёстно с ведомостью эксплуатационных документов), перечисляются носители (например, USB-накопитель с ПО, ключи защиты, лицензия). Если программа поставляется с базой данных или с исходными текстами, это отражается.

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

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

Пример: формуляр программы для медицинской информационной системы может содержать:

• Название: «МИС «Здоровье 1.0», версия 1.0.3».

• Разработчик: ООО «МедСофт», адрес, телефон.

• Дата выпуска: декабрь 2025.

• Язык: C#, платформа .NET 6.

• Назначение: автоматизация поликлиники.

• Характеристики: поддерживает до 200 одновременных рабочих мест, база данных PostgreSQL 14, требует не менее 8 ГБ ОЗУ на сервере.

• Носитель: дистрибутив на DVD, лицензионный ключ USB.

• Документация: Руководство пользователя, Руководство администратора, ПМИ – перечисление (можно дублировать).

• Внедрение: Установлен в ГБУЗ «Городская поликлиника №5» 01.03.2026, ответственное лицо Иванов И.И.

• Отметки об обновлениях: … (пустая таблица для заполнения при обновлениях).

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

---

Перечисленные виды документов – далеко не полный перечень ЕСПД, но они наиболее важны. Кроме них в стандартах ЕСПД есть, например, Спецификация (перечень всех модулей программы и документов к ней), Пояснительная записка (содержит обоснование технических решений, часто пишется на стадии эскизного проекта), Описание применения (похоже на руководство, описывает область применения программы, ограничения и минимальную конфигурацию оборудованияtechwrconsult.com) и Руководство системного программиста (документ для специалиста, который будет программу устанавливать и настроивать на конкретной системе, он содержит, например, инструкции по адаптации ПО к конкретному вычислительному комплексуtechwrconsult.com). Однако подробно их рассматривать не будем, чтобы не перегружать материал. В конкретных проектах состав документов определяется в ТЗ: в самом начале проекта решают, какие документы будут разрабатываться, а какие нет (часть документов может быть признана избыточной для данной работы)techwrconsult.com.

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

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

• Для тестировщиков – ПМИ, спецификации тестов, отчеты об испытаниях; эти документы более технические, связаны с требованиями и показывают, как убедиться в работоспособности.

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

Студентам часто сложно разграничить эти категории: кто читатель документа, тому и должна соответствовать подача. Например, ошибка новичка – написать руководство пользователя как технический документ (со сложными терминами, внутренними деталями) или наоборот, в описании программы скатиться в стилистику мануала для пользователя («эта функция позволяет нажатием кнопки выполнить расчет» – это лишнее для документа разработчика). Всегда держите в уме: «Кому предназначен этот документ?» и «Для какой цели он пишется?» – от этого зависит и содержание, и стиль.

3. Жизненный цикл документации

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

• Начало проекта (стадия формирования требований): на этой ранней стадии рождаются исходные документы. Прежде всего – Техническое задание. Его начинают разрабатывать после предварительных обсуждений концепции. Обычно аналитики совместно с заказчиком формируют ТЗ, согласовывают каждое требование. ТЗ должно быть готово и утверждено до начала основной разработки, так как оно определяет, что делать. Вместе с ТЗ может оформляться Эскизный проект – в ГОСТ 19 это черновая проработка архитектуры и решений, часто сопровождается пояснительной запиской с обоснованием. Но в учебном контексте достаточно помнить, что первым появляется ТЗ. Именно на этапе старта проекта закладывается и план документации: в ТЗ или плане проекта указывают, какие документы будут подготовлены (например, «разрабатываются ТЗ, ПМИ, Руководство пользователя и Формуляр; описание программы не оформляется отдельно» – подобные формулировки могут быть в ТЗ или в договоре).

• Разработка (стадия проектирования и кодирования): в процессе разработки программисты создают исходный код – а по ЕСПД это тоже документ (называется «Текст программы»techwrconsult.com), который подлежит оформлению (включая комментарии). Параллельно, если того требует проект, готовятся Описание программы (разработчик или системный архитектор описывает архитектуру) и Пояснительная записка (обоснование технических решений). Эти документы обычно пишутся ближе к завершению разработки, когда уже понятно, как система реализована. Они могут оформляться задним числом, что не идеально, но часто практикуется: сначала написать код, а потом описать его в документе.

  Кроме того, на стадии разработки могут вестись внутренние документы: спецификации модулей, дизайн-проекты интерфейсов, схемы БД. Формально ГОСТ 19 не накладывает жестких требований на такие документы – организация может оформить их как пояснительную записку или включить в описание программы. В любом случае, к концу стадии разработки у команды должны быть:

  • Актуализированное ТЗ (если за время работы требования уточнялись, официально нужно внести изменения в ТЗ отдельным документом-дополнениемtechwrconsult.com).

  • Обновленные проекты технических решений (схемы, описания) – либо как внутренние документы, либо уже оформленные по стандарту.

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

• Тестирование (стадия испытаний): перед началом финальных испытаний оформляется документ Программа и методика испытаний (ПМИ), о котором мы говорили. Он составляется отделом тестирования или ответственным лицом и утверждается (для приемочных испытаний обязательно официальное утверждение ПМИ, часто вместе с ТЗ). Дальше по ПМИ проводится тестирование:

  • Во время тестирования могут вестись рабочие документы тестировщика: чек-листы, тест-кейсы, протоколы прогона – эти документы могут быть оформлены и не строго по ГОСТ, если они внутренние. Однако итогом испытаний является Акт приемки или Протокол испытаний, где фиксируется, что все испытания по ПМИ проведены и результаты удовлетворительные. Этот акт уже может ссылаться на ПМИ и ТЗ формально.

  • На этапе тестирования часто выявляются разного рода несоответствия, баги. В идеале, серьезные отклонения от требований фиксируются и ведется документирование дефектов (в современном виде – баг-трекер, в ГОСТовском – это могли быть ведомости замечаний, письма и отчеты об ошибках). Если в результате тестов вносятся изменения в программу, то нужно обновлять и документацию: описание программы, руководство пользователя – всё должно отражать финальное состояние ПО.

  • Завершается этап тем, что все документы приводятся в финальный вид: разработчики, тестировщики, технические писатели уточняют тексты, вносят последние исправления. Документирование при тестировании – это непрерывный процесс: по мере нахождения ошибок часто уточняются и требования (например, если какое-то поведение системы не было четко описано в ТЗ, и тестер задал вопрос – это повод уточнить требование и внести ясность в документы). Таким образом, на выходе мы должны иметь: финальную версию ТЗ (при необходимости – с изменениями), ПМИ с отметкой о выполнении испытаний (иногда делают оттиск или отметку «Испытания проведены, протокол №…, программа прошла испытания»), протокол/акт испытаний, и полный комплект эксплуатационных документов, готовых для передачи пользователям.

• Ввод в эксплуатацию (сдача заказчику): на этой стадии документация служит главным подтверждением выполнения работ. Заказчику, помимо самой программы, передают:

  • Техническое задание (утвержденное ранее) – чтобы было с чем сравнить результат.

  • Акт приемки с выводом комиссии, что программа соответствует ТЗ.

  • Программа и методика испытаний + протоколы тестов (как приложения к акту) – чтобы было видно, как проверяли.

  • Эксплуатационная документация (руководства, формуляр, ведомость документов) – чтобы пользователь мог эксплуатировать систему.

  • Исходные тексты (иногда по контракту передаются исходники, иногда нет).

  • Дополнительные материалы: в некоторых случаях – обучающие материалы, презентации, сертификаты соответствия, лицензии на софт, etc., но это уже вне ГОСТ.

  После приемки документация часто становится собственностью заказчика. Сопровождение программы затем предполагает, что при обнаружении ошибок или добавлении нового функционала документацию тоже будут обновлять. По ГОСТ существуют стандарты внесения изменений в документыru.wikipedia.org. Обычно изменения оформляются листами изменений или новыми редакциями документов с пометкой «Изм. №1» и т.д.

• Эксплуатация и сопровождение: на этапе эксплуатации документация используется по назначению:

  • Пользователи обращаются к руководству пользователя при работе.

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

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

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

Резюмируя: жизненный цикл документации тесно связан с жизненным циклом разработки ПО. Документы:

• рождаются на этапе планирования (ТЗ),

• дополняются на этапе проектирования (пояснительная записка, описание программы),

• уточняются и проверяются на этапе тестирования (ПМИ, руководства),

• используются и изменяются на этапе эксплуатации (руководства, формуляр, поддержка).

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

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

4. «Современная документация» vs. формальная (отличия)

На дворе 2025 год, методы разработки шагнули далеко вперед со времен создания ГОСТ 19.x. Agile-подходы, DevOps, постоянная интеграция – все это повлияло и на подход к документированию. Давайте рассмотрим, чем современный подход к документации отличается от классического формального (ГОСТ) подхода.

Формат и инструменты:

• Раньше основными носителями документации были бумажные документы или, в лучшем случае, документы в текстовых редакторах (Word, и до него – машинописные тексты). Сейчас почти вся документация ведется в электронных базах знаний. Популярные инструменты: Confluence, Notion, Wiki. Они позволяют нескольким участникам одновременно редактировать документы, мгновенно публиковать обновления. Документация превращается в «живой» веб-сайт внутри компании, а не статический Word-файл, лежащий в папке.

• Системы трекинга задач (JIRA, Trello, Redmine etc.) и системы управления требованиями (IBM DOORS, Polarion) стали частично заменять собой ТЗ. Требования пишутся в виде пользовательских историй, хранятся и управляются в специальных инструментах, а не оформляются единовременно большим текстом. В любой момент можно сгенерировать спецификацию из базы требований, но мало кто сейчас вручную пишет большой монолитный документ требований, особенно в гибких методологиях.

• Автоматизация документации: Появились средства, которые генерируют документацию напрямую из исходного кода. Например, при разработке API широко применяется Swagger/OpenAPI – по аннотациям в коде сервис автоматически публикует интерактивную документацию (спецификацию REST API), где сразу можно и протестировать запросы. Это экономит время: не нужно писать отдельно документ про API, достаточно поддерживать аннотации в актуальном состоянии, и у вас всегда свежая документацияstudfile.net (в ЕСПД, конечно, ничего подобного не было). Другой пример – генераторы пользовательской документации: современные средства позволяют на основе шаблонов UI или дизайна формировать черновик руководства пользователя, а разработчику остается только добавить описания.

• Живая vs. статичная документация: В agile-мире ценится актуальность информации. Лучше иметь краткую wiki-страницу, но соответствующую последней версии продукта, чем подробнейший ГОСТовский том, давно потерявший связь с реальностью. Принцип «живой документации» означает, что документ постоянно обновляется по мере изменений продукта. Формальные документы же часто страдают тем, что после утверждения их могут забыть обновить при изменениях (особенно если изменения не требуют перезаключения договора).

Объем и детализация:

• Современные методы стремятся к минимально необходимой документации. Agile-манифест провозглашает ценность “работающего программного обеспечения выше исчерпывающей документации”. Это не значит, что документация не нужна вовсе, а значит – не должна создаваться ради процесса, не должна быть избыточной. Например, если команда сидит вместе и постоянно общается, нет смысла писать длинные меморандумы – достаточно user story на пару абзацев. Если требование очевидно из контекста, его могут не дублировать в десяти местах.

• ГОСТовский подход подразумевает исчерпывающую полноту описания на момент сдачи. Это хорошо для приемки (все описано и подписано), но может тянуть за собой лишнюю работу. Например, требование «интерфейс должен быть удобным» – сложно формализовать, а ГОСТ требует фиксировать даже такие моменты (как специальные требования к эргономике). Современная документация скорее опишет экраны и UX в виде прототипов, а не словами в тексте.

Структура и гибкость:

• В стандартах ЕСПД строго определены структура и состав документов. В современном подходе структура документации определяется гибко, под проект. Можно комбинировать документы: например, README файл в репозитории может одновременно служить и техническим описанием, и инструкцией по запуску. В Confluence можно устроить знание в виде дерева статей – разработчики сами решают, на сколько страниц разбить информацию.

• Некоторые типы классических документов трансформировались. Например, спецификация требований в agile заменена бэклогом продукта (набором user story). План тестирования может быть представлен в тест-менеджмент системе (TestRail, Zephyr) или вообще в коде (набор автотестов с описаниями случаев – это тоже документ в некотором роде). Отчет о тестированиичасто заменяется дашбордом в Jira с метриками багов и тестов, вместо толстого отчета по ГОСТ.

• Документация для пользователя в современности часто интегрирована в саму программу: это и всплывающие подсказки, и раздел «Help» в интерфейсе, и веб-порталы поддержки с FAQ. То есть, упор смещается на то, чтобы пользователь не почувствовал необходимости открывать PDF-файл с руководством – программа должна быть самодостаточно понятной, а если помощь нужна, она должна быть в один клик.

Поддержание и ответственность:

• При классическом подходе существовали должности технических писателей, которые оформляли документы по стандартам. Сейчас технические писатели никуда не делись, но их роль изменилась: они становятся модераторами знаний, настраивают базы знаний, пишут user-guides, но разработчики и тестировщики тоже участвуют. В wiki-инструментах любой может поправить страницу, исправить неточность сразу.

• Ответственность за документацию в agile-командах распределенная: каждый отвечает за актуальность артефактов, которые он ведет (разработчик – за описание модуля/README, аналитик – за user story и диаграммы, тестировщик – за тест-кейсы). В итоге нет ситуации «документация устарела, потому что Вася-техписатель не знал об изменениях» – изменения вносятся теми же людьми, кто делает продукт.

Скорость и формальность:

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

• С другой стороны, формальные документы – это юридически значимые артефакты. ТЗ, подписанное сторонами, – часть контракта. Современные легковесные документы юридической силы не имеют (user story в Jira не подпишешь). Поэтому в серьезных контрактах agile-документацию часто «нагружают» формальными соглашениями или минимумом ГОСТовских артефактов, чтобы и гибкость сохранить, и контракт был покрыт. Например, могут договориться: «Вместо классического ТЗ стороны утвердят документ Vision (описание продукта) + backlog в Jira приложением к договору». Это компромиссный вариант.

Подведем итог сравнений в небольшой таблице:

Конечно, не все проекты одинаково «гибкие». Есть отрасли (банк, авто, авиа), где и в 2025 году требуют отчеты и ТЗ по ГОСТ. А есть стартапы, где нет вообще никакой документации кроме исходного кода и пары страниц wiki. Хороший инженер по качеству (QA) или аналитик должен понимать оба подхода и применять элементы в зависимости от ситуации. Например, в гибком проекте полезно знать структуру ГОСТовского ТЗ, чтобы не упустить разные виды требований, но оформить их можно user story. А в строгом проекте по ГОСТ можно применять современные инструменты для удобства: например, генерацию документации в Word из Confluence-страниц, чтобы иметь и живую wiki, и форму для заказчика.

5. Сравнение ЕСПД и современного подхода: задачи и ценности

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

ЕСПД (формальная документация) решает следующие задачи:

• Контрактная определенность: чётко зафиксировать, что должно быть сделано (ТЗ), как будет проверяться (ПМИ), и на основании чего принимать работу. Это защищает и заказчика, и исполнителя от недопонимания. Например, если в ТЗ описано требование, то заказчик не сможет потребовать сверх того без изменения ТЗ; а исполнитель обязуется выполнить всё, что там написано.

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

• Унификация для массового применения: исторически ЕСПД создавалась, чтобы на государственном уровне унифицировать документацию. Например, есть тысячи программистов в советских НИИ – их надо обучить одному формату. ЕСПД давала эту общую основу. Сейчас, хотя стандарт и не обязателен, отголоски чувствуется: ГОСТ 19 лег в основу многих учебных программ (как у нас сейчас), в основу некоторых корпоративных стандартов. Если специалист изучил принципы ЕСПД, ему легче понять документацию по ГОСТ 34 или требования регуляторов (например, в оборонной или космической сфере).

• Формальность при сертификации: для сертификации ПО (например, получение сертификата ФСТЭК по безопасности) требуется определенный комплект документов. ГОСТы тут пригождаются – по ним легко проверить, все ли аспекты раскрыты. Сертифицирующие органы привыкли видеть ТЗ, ПМИ, руководства – им так удобнее ставить галочки.

Современный (гибкий) подход к документации решает свои задачи:

• Скорость реакции на изменения: информация в документации может меняться еженедельно вместе с продуктом. Команда сразу видит актуальную постановку задачи, быстро вносит коррективы. Это снижает риск работать по устаревшим требованиям. Например, изменился бизнес-процесс – аналитик обновил пользовательскую историю, разработчик тут же получил новую версию требований, тестировщик поправил тест-кейсы. Никто не ждет переподписания 100-страничного ТЗ.

• Прозрачность и коммуникация: инструменты типа Jira+Confluence делают требования и документацию прозрачными для всех участников в реальном времени. Любой член команды может зайти и увидеть состояние проекта: какие требования в работе, что уже сделано, какие тесты прошли. В классическом подходе, чтобы понять состояние проекта, надо читать отчеты или спрашивать у руководителя – в agile же всё на виду (доска задач, burn-down chart, страницы с дизайном и т.д.).

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

• Интеграция с процессом разработки: документация становится частью процесса: автогенерация API-документа – часть сборки, написание unit-тестов с описаниями – часть кодинга, поддержка wiki – часть Definition of Done. В итоге документация не живет отдельной жизнью, а всегда идет рука об руку с кодом. Это повышает ее актуальность и снижает трудозатраты на поддержку (потому что изменения делаются сразу, а не потом отдельной задачей).

Области применения: можно сказать, что формальный подход более оправдан:

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

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

• в учебном процессе – чтобы структурировать мышление.

Современный подход эффективен:

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

• в кросс-функциональных командах, где все общаются напрямую – документы играют роль справочников, а не юридических артефактов;

• когда приоритет – скорость вывода продукта на рынок, и формальности можно отложить (MVP, прототипирование).

В реальной жизни часто комбинируют оба подхода. Например, BDD (Behavior Driven Development) – это когда требования пишутся в виде выполняемых сценариев (SpecFlow, Gherkin синтаксис: «Дано… Когда… Тогда…») – такая спецификация одновременно и документ читабельный для человека, и автотест. Она удовлетворяет и стремление к формализации (все поведение расписано), и современность (исполняется автоматически, живет в репозитории с кодом).

Еще пример: user story + acceptance criteria – по сути то же ТЗ, только мелкими частями. Каждая user story содержит критерии приемки (acceptance criteria), которые очень похожи на пункты ПМИ (описано, что проверить). Просто они хранятся не в одном документе, а в базе задач. Но если надо – их можно собрать и получить документ.

Вывод: ЕСПД и современный подход имеют разные ценности, но общая цель – сделать так, чтобы все заинтересованные лица имели нужную информацию о продукте в понятной форме. Формализм ЕСПД полезен для порядка и ответственности, гибкость нового подхода – для скорости и эффективности. Хороший специалист должен уметь извлекать лучшее из обоих: дисциплину и структурность ГОСТ – и адаптивность и практичность agile-документации.

6. Примеры и разбор документов

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

6.1. Структура реального ТЗ (пример)

Предположим, нам нужно составить техническое задание на разработку мобильного приложения для онлайн-магазина. Как бы выглядело оглавление такого ТЗ по ГОСТ?

Пример оглавления ТЗ:

1. Наименование и область применения:
   «Техническое задание на разработку мобильного приложения “ShopMobile” для системы электронного магазина. Приложение предназначено для использования покупателями интернет-магазина ООО “ShopOnline” с целью просмотра каталога и оформления заказов через смартфоны.» (Это название и 2-3 предложения о том, где применяется).

2. Основание для разработки:
   – Договор №… от … или Приказ компании №… – что послужило стартом.
   – Инициатор: например, директор по ИТ такой-то компании.
   – (Если есть госномер темы или приказ Минцифры – указывается).

3. Назначение разработки:
   «Цель создания приложения – обеспечить пользователям удобный мобильный доступ к возможностям интернет-магазина “ShopOnline”, повысить лояльность клиентов и объем мобильных продаж.»
   (Т.е. зачем делаем – суть).

4. Требования к программе: (подразделы)

   • Требования к функциональным характеристикам:
     – Приложение должно предоставлять функции регистрации/входа пользователя.
     – Просмотр каталога товаров с фильтрацией и поиском.
     – Управление корзиной и оформление заказа, выбор способа оплаты и доставки.
     – Просмотр статуса выполненных заказов.
     – Получение уведомлений о акциях и статусе заказов (push-уведомления).
     (Перечисляется весь основной функционал подробно).

   • Требования к удобству использования (эргономике): (Этого пункта нет явно в ГОСТ, но его можно отнести к спец. требованиям)
     – Интерфейс должен соответствовать гайдлайнам iOS Human Interface Guidelines и Material Design (для Android).
     – Приложение должно поддерживать два языка: русский и английский (локализация).

   • Требования к надежности:
     – Приложение должно корректно работать при временном отсутствии сети (отображать кешированные данные, ставить действия в очередь).
     – Должна быть реализована система логирования ошибок с отправкой на сервер при подключении.
     – … и т.п.

   • Условия эксплуатации:
     – Поддерживаемые платформы: iOS 13+ и Android 9+;
     – Работа при подключении к интернету (Wi-Fi, 4G);
     – Окружение: серверная часть API, URL такой-то (возможно, тут или в описании программы).
     – Ограничения: приложение не предназначено для планшетов в первой версии, и т.д.

   • Требования к техническим средствам:
     – Телефон с минимально 2 ГБ ОЗУ, 4-ядерным процессором;
     – Свободная память для установки не менее 100 МБ;
     – … (если релевантно).

   • Требования к информационной совместимости:
     – Приложение должно работать с API сайта версии 3.0 (протокол HTTP/HTTPS, формат JSON, описание API – в документе таком-то).
     – Должно поддерживать авторизацию через OAuth2 (если используем соцсети – то указывается).

   • Специальные требования:
     – Безопасность: данные пользователя (логин, пароль, токены) должны храниться в зашифрованном виде;
     – Защита персональных данных: соответствие Федеральному закону РФ №152-ФЗ (о персональных данных).
     – Требования к маркировке и упаковке: (для ПО обычно не применимо, можно написать «Программный продукт распространяется через App Store и Google Play, на материальных носителях не распространяется»).
     – … и т.д.

5. Технико-экономические показатели:
   – Ожидаемое количество пользователей: до 10000 активных в день.
   – Экономический эффект: увеличение конверсии мобильных пользователей на 15%.
   – (Эти показатели труднее формулировать, могут быть опущены или описаны качественно).

6. Стадии и этапы разработки:
   – Этап 1: Анализ и разработка ТЗ (сроки: январь 2025, исполнители…).
   – Этап 2: Разработка прототипа UX/UI (февраль 2025).
   – Этап 3: Разработка программного кода (март–май 2025).
   – Этап 4: Тестирование (июнь 2025).
   – Этап 5: Внедрение и приемо-сдаточные испытания (июль 2025).
   (Эти стадии могли бы быть и проще – но важно указать, что, например, будет опытная эксплуатация, доработка по ее результатам, и т.п., если планируется).

7. Порядок контроля и приемки:
   – Кто проводит испытания: отдел тестирования разработчика + представители заказчика.
   – Какой документ будет итогом: Акт приемочных испытаний.
   – Критерии приемки: отсутствие критических дефектов, выполнены все требования раздела 4 ТЗ, время отклика не превышает указанных значений и т.п.
   – Особые условия: например, «приемка проводится на устройствах: iPhone 11, Samsung Galaxy S20, …; считается успешной, если на всех указанных устройствах пройдены тесты.»

8. Приложения:
   – Эскизы экранов (можно приложить прототип интерфейса).
   – Описание архитектуры (если уже есть какая-то схема, можно включить).
   – Материалы анализа (например, ссылка на документ с пользовательскими историями, если он существует отдельно).

Это лишь пример, но он демонстрирует уровень детализации и стиль изложения в ТЗ: формальный, однозначный, нумерованный. Каждое требование обычно пронумеровано (4.1, 4.1.1 и т.д.) для удобства ссылки в тестах.

Обратите внимание, что в современных компанияи вместо такого ТЗ могли бы использовать документ Software Requirement Specification (SRS) или набор эпиков и user story. Но структура похожая: описание функционала, нефункциональных требований, критериев приемки. ГОСТовское наследие прослеживается даже в современном SRS.

6.2. Структура ПМИ (пример)

Возьмем тот же пример – мобильное приложение магазина – и подумаем, как выглядел бы фрагмент ПМИ для него.

Пример содержания ПМИ:

• Объект испытаний: «Мобильное приложение “ShopMobile” версии 1.0, сборка №123 для iOS/Android.» (Указываем конкретно, что тестируем).

• Цель испытаний: «Установить соответствие приложения требованиям технического задания и готовность к опытной эксплуатации пользователями.» (Можно добавить, что цель – проверить все функции, надежность и т.д.).

• Требования к программе (подлежащие проверке): Здесь перечисляем все пункты из раздела 4 ТЗ, которые мы написали, например:

  1. Функциональные требования:
     1.1 Пользовательская регистрация/авторизация – подлежит проверке.
     1.2 Просмотр каталога с фильтрацией – подлежит проверке.
     … и так далее по каждому подпункту.
     1.5 Оформление заказа – подлежит проверке.

  2. Требования к надежности:
     2.1 Работа при отсутствии сети (офлайн режим) – подлежит проверке.
     2.2 Восстановление после сбоя – подлежит проверке (например, что приложение не теряет корзину после перезапуска).

  3. Условия эксплуатации:
     3.1 Работа на поддерживаемых ОС (iOS13, Android9) – подлежит проверке (фактически, нужно тестировать на указанных платформах).
     3.2 Работа при разных типах подключения сети – подлежит проверке (Wi-Fi vs 4G).

  4. Специальные требования:
     4.1 Шифрование данных – подлежит проверке (нужно убедиться, что, например, пароли не хранятся в открытом виде и т.д.).
     … и т.д.

  То есть мы создаем списком все важные требования, отметив, что их надо проверить. В ГОСТ формулируется: «требования, предъявленные в ТЗ, подлежащие проверке: …»techwrconsult.com.

• Требования к документации: В нашем примере:
  «Наличие и полнота эксплуатационных документов: должно быть представлено руководство пользователя приложения. Методика проверки: сверка содержания руководства с требованиями ТЗ.»
  Если были другие документы, их тоже перечисляют. Например: «Формуляр программы – наличие, проверка заполнения основных характеристик.»
  Этот раздел гарантирует, что проверят не только программу, но и документы (часто забываемый момент!).

• Средства и порядок испытаний:
  Здесь укажем:
  – Тестирование проводится на реальных устройствах: не менее 2 моделей на iOS (например, iPhone 13, iPhone 8) и 2 на Android (Samsung Galaxy S20, Xiaomi Redmi…), с версиями ОС как в требованиях.
  – Программные средства: эмулятор сервера (если нужен), тестовые учетные записи на сервере магазина (список логинов/паролей).
  – Порядок: сначала проводится функциональное тестирование основных сценариев (smoke tests: запуск приложения, регистрация, просмотр каталога, заказ), затем подробное тестирование всех функций по разделам требований, затем нагрузочное тестирование (например, имитация 1000 пользователей), и в конце – испытание на отказоустойчивость (отключение сети, некорректные данные).
  – Указывается, кто проводит: «Испытания проводят инженеры тестирования ООО “DevTeam”, при участии представителя заказчика на приемочных тестах.»

• Методы испытаний:
  Обычно оформляется в связке с предыдущим разделом, но можно расписать по пунктам:
  Для каждого требования описывается метод:
  1.1 Проверка регистрации: метод – функциональный тест. Порядок: запустить приложение, попытаться зарегистрироваться с корректными данными -> ожидаемый результат: успешная регистрация; повторить с некорректными данными (пустой пароль, неправильный email) -> ожидаемый результат: соответствующие сообщения об ошибке. Средства: список тестовых учетных данных в Приложении А.
  1.2 Проверка фильтрации каталога: метод – функциональный тест, ручной. Порядок: открыть каталог, задать фильтр (категория “Телефоны”), убедиться, что в списке только телефоны. Далее задать диапазон цен, проверить… и т.п. Ожидаемый результат: товары вне диапазона скрыты.
  …
  1.5 Проверка оформления заказа: метод – функциональный тест + интеграционный. Порядок: положить товар в корзину, оформить заказ, уплатив тестовой картой (номер карты тестовой указать). Проверить на сервере (через админ-панель, либо БД), что заказ зафиксирован правильно. Ожидаемый результат: на экране – сообщение об успешном оформлении с номером заказа; в базе – запись заказа со статусом “Новый”.
  2.1 Проверка офлайн режима: метод – тестирование устойчивости. Порядок: запустить приложение онлайн, перейти в каталог; выключить интернет на устройстве; попробовать открыть другой раздел – ожидается сообщение “Нет подключения” и отображение ранее загруженных данных из кеша. Затем снова включить интернет, убедиться, что приложение автоматически продолжило работу.
  3.1 Проверка на платформах: метод – проверка совместимости. Порядок: выполнить тесты из пп.1.1–1.5 на устройствах: перечисляются модели… Ожидаемый результат: функциональность идентична, существенных расхождений нет, все тесты проходят.
  4.1 Проверка шифрования: метод – анализ кода и тестирование безопасности. Порядок: после регистрации пользователя открыть локальное хранилище приложения (KeyChain в iOS, Keystore в Android) и убедиться, что пароль или токен не хранятся в открытом виде. Ожидаемый результат: пароль не обнаружен, токен сохранен в зашифрованном виде (или не сохраняется локально вовсе).

  И так далее по каждому требованию. Методы могут быть различны: где-то достаточно наблюдения, где-то нужны специальные инструменты (например, для нагрузки – использовать JMeter с сценариями API). Все это описывается. Конечно, ПМИ не расписывает каждый мелкий тест-кейс, скорее, группирует. Например, вместо 10 кейсов по фильтрации можно написать одно описание метода испытаний, охватывающее граничные случаи.

• Приложения к ПМИ:
  Здесь можно приложить таблицы тестовых данных, например:
  – Приложение А: Таблица тестовых учетных записей (логин/пароль для теста).
  – Приложение B: Скриншоты ключевых шагов тестирования (не обязательно, но бывает).
  – Приложение C: Отчеты производительности (графики времени отклика при нагрузке).
  – Приложение D: Протокол автоматизированного теста безопасности (если прогоняли статический анализатор или тест на OWASP).

Как видно, ПМИ – объемный документ, по сути это методика проверки соответствия ТЗ. В реальных проектах часто вместо одного ПМИ делают набор отдельных документов: план тестирования, набор тест-кейсов (в Excel, TestRail), отчет о тестировании. Но принцип тот же: вначале сверяемся с требованиями, потом описываем, как проверяем.

6.3. Скелет «Руководства пользователя»

Возьмем пример попроще: предположим, у нас настольное приложение «Учет личных финансов». Что должно быть в руководстве пользователя (оператора) к нему?

Пример структуры руководства пользователя:

• Введение (Назначение программы):
  «Программа “Домашняя бухгалтерия” предназначена для учета личных доходов и расходов. Она позволяет пользователю фиксировать финансовые операции, планировать бюджет и просматривать статистику трат.»
  Здесь же можно указать версию программы, кем разработана (иногда это титульная информация).

• Условия выполнения программы:
  – Операционная система: Windows 10/11 либо Linux (Ubuntu) – (перечислить поддерживаемые).
  – Требуемое место на диске: 50 МБ.
  – Прочие требования: наличие установленного .NET Framework 4.8, либо JRE 11 – зависит на чем приложение.
  – Права: пользователь должен иметь права на запись в свой профиль (обычно это подразумевается, но если нужны админ-права – обязательно указать).
  – Окружение: если программа, например, интегрируется с банком через интернет, то и это можно упомянуть: доступ в интернет для обновления курсов валют.

• Установка программы:

  1. Запуск установщика HomeFinanceSetup.exe.

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

  3. Создание ярлыка на рабочем столе.

  4. Требуемые компоненты: (например, «если не установлен .NET, установщик предложит загрузить – согласитесь»).

  5. Завершение установки: «после установки запустите программу через меню Пуск или ярлык».

• Начало работы (Запуск программы):
  – Как запустить, как выглядит главное окно. Возможно, скриншот главного окна с пометками основных разделов.
  – Описание элементов главного интерфейса: меню, кнопки, панели. «На верхней панели расположены кнопки: ‘Новая транзакция’, ‘Отчет’, ‘Настройки’. В левой части – список счетов пользователя. В центральной – таблица операций.»

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

  • Добавление новой операции (доход или расход):
    Шаг 1: нажать кнопку «Новая транзакция».
    Шаг 2: В появившемся окне заполнить поля: сумма, категория, дата, комментарий (необязательно).
    Шаг 3: Нажать «Сохранить».
    Ожидаемый результат: новая операция появится в списке операций, баланс счета обновится.
    (Привести рисунок окна добавления операции со стрелками, обозначающими поля).

  • Редактирование и удаление операций:
    Описать, как выбрать операцию, нажать «Редактировать» или «Удалить», подтверждение удаления.
    Внимание: удаленные операции нельзя восстановить (если так).

  • Создание счета:
    Шаг 1: Меню «Справочники» -> «Счета» -> кнопка «Добавить счет».
    Шаг 2: Ввести название счета (например, «Наличка», «Карта VISA…»), начальный баланс.
    Шаг 3: Сохранить.
    Новый счет появится в списке слева.

  • Просмотр отчетов:
    Шаг 1: Меню «Отчеты» -> выбрать период (например, месяц).
    Шаг 2: Выбрать тип отчета: диаграмма расходов по категориям.
    Шаг 3: Нажать «Сформировать».
    Отобразится график, его интерпретация: «самый большой сектор – категория ‘Еда’, 30% расхода».
    (Возможно, показать пример графика).

• Настройки программы:
  Описать раздел настроек: «В меню ‘Настройки’ можно изменить валюту по умолчанию, язык интерфейса (русский/английский), установить пароль на вход в программу, включить автосохранение…».
  Каждый пункт настроек – коротко что делает. Например, настройка «Автоматическое сохранение» – объяснить, что программа будет сохранять данные каждые 5 минут в файл.

• Сообщения и ошибки:
  Здесь перечисляем типичные сообщения:
  – «Ошибка: недостаточно прав для записи» – возникает, если папка базы данных недоступна для записи. Действие: запустить программу от имени администратора или изменить права доступа.
  – «Внимание: не выбран счет» – появляется, если пользователь пытается добавить операцию без счета. Действие: выбрать счет из списка слева.
  – «Данные сохранены» – информативное, появляется при успешном резервном копировании базы (в настройках).
  Если программа может обновляться: «Доступно обновление версии 1.1» – руководство скажет, что нужно согласиться и дождаться перезапуска.

• Часто задаваемые вопросы (FAQ): (необязательный раздел, но часто полезен)
  Q: «Можно ли установить программу на несколько компьютеров?» – A: Да, но база данных локальна для каждого ПК, синхронизация… (если есть, описать).
  Q: «Как восстановить забытый пароль?» – A: Никак, храните пароль… (или описать, что делать).
  Q: «Где хранится файл с данными?» – A: По умолчанию в Моих Документах, файл finance.db.

• Обновление программы:
  Если предусмотрено, описать: «для обновления скачайте новую версию с сайта, запустите установщик поверх старой – все ваши данные сохранятся.» Или: «Обновления устанавливаются автоматически при наличии интернета, достаточно подтвердить запрос.»

• Заключение (при необходимости):
  Можно указать контакты техподдержки, версию документации, отсылку к другим документам (например, «подробное описание алгоритмов приведено в описании программы, доступном по запросу»).

Как видим, руководство пользователя – пошагово ориентированный документ. В нем много нумерованных списков («шаг 1, 2, 3»), скриншотов с пометками (в печатных ГОСТ-руководствах скриншоты тоже были, хотя стандартом это не описано, но обычно включали рисунки). Язык максимально простой: никаких “модулей, баз данных” – вместо этого “ваши данные хранятся в файле…”.

Типичные ошибки студентов при написании руководства пользователя:

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

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

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

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

7. Типичные ошибки студентов и новичков в документации

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

• Путаница между видами документов. Например, некоторые студенты, получив задание написать «тестовую документацию», начинают описывать в ней и требования, и архитектуру, и результаты – то есть смешивают всё в кучу. Нужно четко различать: проектная документация (ТЗ, дизайн, архитектура) описывает систему и требования к ней, а тестовая документация (план тестирования, случаи, отчеты) описывает процесс проверки системы. Они имеют разное назначение и стиль. Если попросили написать ПМИ, не нужно туда копировать куски руководства пользователя или описания программы (кроме тех, что нужны для контекста тестов).

• Отсутствие структуры, логики изложения. Новички часто пишут «потоком сознания». Например, берутся писать ТЗ и сразу смешивают требования разного уровня: «Программа должна быть удобной. Пользователь вводит логин и пароль. Должна обеспечиваться защита данных.» – всё в одном абзаце без структуры. Правильно: разбить по подразделам, каждое требование формулировать четко, отдельно. Структура – это скелет документа. Если ее нет, документ сложно читать, а автор сам путается, что где написал. Совет: перед написанием сделать план – выписать разделы и подпункты, а уже потом заполнять.

• Отсутствие связки с требованиями. Документация должна быть взаимоувязанной. Тестовые сценарии должны отсылать к требованиям, требования – прослеживаться в тестах, руководства – покрывать использование тех функций, которые есть. Новички часто пишут документы изолированно. Например, в ПМИ перечислены не все требования из ТЗ (что-то забыли – а значит, не протестируют!) или в руководстве пользователя описана функция, которой нет в требованиях (потому что они, допустим, придумали сами, не согласовав – это тоже проблема). В индустрии используют практику трассировки требований (requirements traceability): таблицы, матрицы, чтобы видеть, что на каждый пункт ТЗ есть тест, в руководство включено все функциональные возможности и т.д. Вам пока достаточно просто внимательно сверять: написал требование – подумай, где оно отразится еще? Написал тест – с каким требованием он связан?

• Смешение цели и средств. Эту ошибку мы уже упоминали: особенно в требованиях (ТЗ) нельзя впадать в описание реализации. Требование – это что нужно, критерий приемки – как узнать, что сделано, а реализация – как сделать. Начинающие часто либо уходят в императив (как сделать), либо наоборот, в ТЗ описывают тесты. Пример ошибки: в разделе требований написать «Для проверки выполнения программы будет использоваться такая-то утилита» – это лишнее, место этому в ПМИ. Или в ПМИ (методика испытаний) вдруг начать излагать, как программа должна работать – вместо того, чтобы писать, как проверять. Каждый документ имеет свою «зону ответственности».

• Неучет аудитории документа. Еще раз подчеркнем: кто читатель? Стиль изложения для пользователя: пошаговый, без жаргона. Для разработчика: точный, можно со схемами, можно техническим языком. Для менеджера/заказчика (ТЗ): четкий, однозначный, но без избыточных тех. деталей. Неадаптация стиля – частая проблема. Представьте, вы написали руководство, а пользователь его открыл и ничего не понял – значит документ не выполняет свою функцию.

• Орфография, терминология, оформление. Хотя это не чисто методическая ошибка, но стоит упомянуть. Документ, напичканный опечатками, с разнобоем терминов (то «программа», то «приложение», то «система» без пояснения, что это одно и то же), с кривыми заголовками – производит плохое впечатление и может даже повлиять на оценку/решение заказчика. Формальная документация требует аккуратности. Пользуйтесь проверкой орфографии, перечитывайте текст. Термины вводите: если аббревиатура – расшифруйте при первом упоминании. Единицы измерения, форматы – соблюдайте (ГОСТ, кстати, содержит много правил по оформлению – например, как единицы писать, но это детали).

• Документирование ради документа. Иногда увлекаются и пишут много лишнего, не приносящего пользы. Например, целую страницу «Введение» с историей развития ПО – хотя никому это не нужно для целей данного дока. Или в руководстве пользователя переписывают части ТЗ («Наша программа предназначена для повышения того-то…») – пользователь хочет знать конкретно, как ей пользоваться, а не читать маркетинг. Учитесь отделять главное от второстепенного. Золотое правило: каждый раздел документа должен иметь четкую цель и ценность. Если раздел ни на что не влияет, его не должно быть. В ТЗ не пишем про «методы разработки» (бывает и такое творчество у студентов) – заказчику все равно, на React или Angular вы сделаете, ему главное функционал. А вот в описании программы можно написать про технологию, потому что тому, кто будет сопровождать, это важно.

• Необоснованное копирование и дублирование. С появлением интернета студенты иногда берут чьи-то готовые документы и пытаются адаптировать. Плохо, когда адаптация формальна: в итоге требования частично не относятся к вашей задаче, читающий видит противоречия. Лучше написать свое, пусть более простое, чем копировать сложное, не до конца понимая. Также внутри документа не должно быть дублирования одного и того же текста – если что-то должно фигурировать и там, и там, лучше сделать ссылку или вынести в приложение. Дублирование опасно тем, что поправят в одном месте, а в другом забудут – появится конфликт версий.

Совет: после написания документа самостоятельно проведите ревизию по чек-листу:

1. Все ли требования/пункты, которые должны быть, на месте? (Свериться со стандартной структурой).

2. Нет ли противоречий внутри документа? (Например, в одном разделе написано одно, в другом – другое про ту же вещь).

3. Ясна ли терминология? (Если ввели новое понятие – объяснили ли его?)

4. Поставьте себя на место читателя-новичка и прочтите – все ли понятно без дополнительных вопросов?

Если на все ответ «да» – документ, скорее всего, хорошего качества.

[task_id id=»20437″]