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

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

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

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

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

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

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

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

Слабая формулировка: “программа предназначена для автоматизации учета”. Она слишком широкая и не показывает границы ответственности.

Рабочая формулировка: “программа предназначена для приема заявок от клиентов, проверки обязательных данных, маршрутизации заявок ответственным сотрудникам и передачи статусов во внешнюю CRM через API”. Такая формулировка показывает пользователей, основные действия, данные и интеграционный контур.

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

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

Общая схема ролей документов в проектной документации показана на странице технического проекта по ГОСТ 34.

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

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

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