Документация на программное обеспечение
Документация — это не просто формальность. Мы покажем, как структурировать проектную и техническую документацию на ПО так, чтобы она обеспечивала устойчивость, прозрачность и соответствие ГОСТ и ISO.
структура и стандарты ГОСТ 34, ГОСТ 19, ISO и IEEE
Проектная и техническая документация — это неотъемлемая часть жизненного цикла программного обеспечения. В Etence мы выстраиваем системный подход к документации, чтобы обеспечить управляемость, масштабируемость и прозрачность решений как для внутренних команд, так и для клиентов.
Эта статья описывает, как организована документация на программное обеспечение в Etence, какие документы формируются, зачем они нужны и каким стандартам соответствуют.
Почему документация имеет значение
Отсутствие структурированной документации приводит к неясности, дублированию решений и потере управляемости. Особенно это критично для сложных, распределённых или долгосрочных проектов. Мы рассматриваем документацию как инструмент:
- фиксации архитектурных и организационных решений;
- воспроизводимости при масштабировании или передаче проекта;
- соблюдения регуляторных и отраслевых требований (ГОСТ, ISO);
- прозрачности для всех участников процесса.
Подробнее о подходе:
Как в Etence организована документация на программное обеспечение
Документы классифицируются по стадиям жизненного цикла и назначению. Мы следуем принципам гибкости: для небольших проектов применяем укрупнённые шаблоны, для государственных и инфраструктурных — полную детализацию.
Документы стадии инициации проекта
Назначение: формулировка замысла, обоснование проекта, определение границ и рисков.
- Концепция проекта (Concept Note) — идея, цели, проблемы, ожидаемые эффекты. ГОСТ 34.201-89, Vision Document, IEEE 1062.
- Предварительный обзор проекта (Initial Review) — анализ рисков, ограничений, ключевых допущений и зависимостей.
- Обоснование целесообразности (Feasibility Study) — анализ технической и ресурсной реализуемости. ISO/IEC 15288: Feasibility Assessment.
- Бизнес-обоснование (Business Case) — экономика, стратегия, оценка выгод и затрат. PMBOK, ISO 15686.
- Эскизный проект (ЭП, Preliminary Design, High-Level Concept, Conceptual Architecture, BRD) — предварительная архитектура (HLD представлен в виде архитектурной концепции), состав и структура системы, ключевые модули, способы интеграции и принципы построения. ГОСТ 34.201–89, соответствует High-Level Design (HLD).
- Запрос информации (RFI) — вспомогательный документ, используемый при сравнении решений или выборе подрядчиков. Не формализован в ГОСТ, соответствует практике PMBOK.
- Техническое задание (ТЗ, Requirements Specification) — официальный документ, завершающий стадию инициации и определяющий требования к создаваемой системе. Включает цели, функции, состав работ, требования к архитектуре и ограничения. ГОСТ 34.602–89, IEEE 830.
Архитектурные и системные документы
Назначение: фиксируют архитектуру, состав, структуру программных компонентов, а также интерфейсы и данные, передаваемые между ними. Используются на стадии проектирования и при передаче проекта в разработку. Формируют основу высокоуровневого проектирования (High-Level Design, HLD) и служат входом для создания рабочей документации (РД) / Low-Level Design (LLD).
- Технический проект (ТП, Technical Design, HLD) — ключевой документ стадии проектирования, фиксирующий архитектуру (HLD получает инженерную формализацию), функциональные и нефункциональные требования, логику работы, структуру программ и способы взаимодействия. ГОСТ 34.603–92 (ТП), IEEE 830 (SRS), ISO/IEC/IEEE 42010 (Architecture Description).
- Описание структуры программы (Program Structure Description) – иерархия программных компонентов, их назначение, состав и внутренние связи на стыке HLD и LLD. Может включать схемы и таблицы модулей. ГОСТ 19.402–78, ISO/IEC 42010, SBOM (по ISO 5230).
- Рабочая документация (РД, Low-Level Design / Implementation Specification) – детализация решений, описанных в ТП, до уровня, необходимого для реализации, настройки и сопровождения программной системы. ГОСТ 19.402–78 (структура программы), ISO/IEC 24765 (Implementation), IEEE 1016 (Software Design Description – LLD).
- Описание протокола взаимодействия программ (Inter-Program Interface Specification) – интерфейсы между программами, модулями, компонентами. ГОСТ 19.502, ISO 42010, OpenAPI, gRPC IDL, GraphQL.
- Описание входных и выходных данных (Input/Output Data Description) – описание всех параметров, полей, типов данных, ограничений и форматов. ГОСТ 19.503, ISO/IEC 11179 (Data Dictionary).
Функциональные и интерфейсные спецификации
- Описание функциональных характеристик ПО – только внутренняя логика, модули, параметры, алгоритмы. ГОСТ 19.101 / Functional Spec (часть SRS)
- Описание пользовательских интерфейсов (User Interface Specification) — экраны, элементы, реакции, UX. ГОСТ 19.505 + ISO 9241 / ISO/IEC 25062
Реализация, сборка и разработка
Назначение: обеспечить воспроизводимость и стандарты разработки.
- Инструкция по установке и развёртыванию (Build Guide) — шаги установки, окружения, зависимости, команды CI/CD. ГОСТ 19.506.
- Руководство по разработке (Development Guide) — git-процессы, коммиты, ревью, правила внесения изменений. ISO/IEC/IEEE 26515.
- Описание исходного кода (Source Code Structure) — структура проекта, особенности реализации, соглашения по кодированию. IEEE 1016 / ISO/IEC/IEEE 24765.
Испытания и проверка
- Программа и методика испытаний (ПМИ) — подход к тестированию, критерии приёмки, условия и этапы проведения испытаний. ГОСТ 19.301, ГОСТ 34.601, IEEE 829 / ISO/IEC/IEEE 29119.
- Протоколы испытаний — отдельные документы по результатам выполнения ПМИ. Фиксируют, какие тесты проведены, их результаты, отклонения, даты и подписи ответственных. ISO/IEC 12207 (Verification Records).
Эксплуатация и сопровождение
Назначение: эксплуатация, обновления, сопровождение.
- Руководство пользователя (User Manual) — инструкции, сценарии, подсказки, интерфейс. ГОСТ 19.505.
- Руководство администратора (Admin Manual) — установка, настройка, резервное копирование, безопасность. ГОСТ 19.506
- Регламент сопровождения (Support Plan) — жизненный цикл поддержки, ошибки, обновления, роли. ISO/IEC 14764 / ITIL.
- Документация по инфраструктуре (Infrastructure Guide) — git, CI/CD, зеркала, сервера.
- Описание процессов жизненного цикла программного обеспечения (Lifecycle Managment Plan) – этапы разработки, обновлений, сопровождения и развития ПО. ISO/IEC 12207, ГОСТ 34.201.
Подробнее о составе и назначении эксплуатационной документации — в отдельной статье.
Паспорта и регистрация
- Паспорт системы (System Passport) — версия, сборка, состав, платформа. ГОСТ 2.601.
- Описание программного продукта (Product Description) — используется для реестра российского ПО. По приказу Минцифры и методичке ЦКИТ.
- Механизмы лицензирования и поставки – Механизмы лицензирования и поставки — в соответствии с ISO/IEC 19770, могут быть оформлены как часть сопровождающей документации.
ГОСТ 34 и ГОСТ 19: стандарты проектной документации на программное обеспечение
Стандарты ГОСТ 34 и ГОСТ 19 формируют основу для формализации проектной документации. Мы применяем их адаптированно: сохраняя структуру и смысл, но не перегружая команды избыточной формальностью.
ГОСТ 34: жизненный цикл автоматизированных систем
- ГОСТ 34.201–89 – определяет стадии проектирования и состав проектной документации (ТЗ, ТП, РП, ПМИ, эксплуатация).
- ГОСТ 34.201.4–89 – эксплуатационная документация.
- ГОСТ 34.602–89 – структура технического задания / ТЗ (цели, требования, ограничения, порядок приёмки).
- ГОСТ 34.603–92 – структура технического проекта.
- ГОСТ 34.601–90 – программа и методика испытаний.
ГОСТ 34 применяется при проектировании архитектуры, фиксации требований, передаче проектов на поддержку.
ГОСТ 19: документация на программное обеспечение
- ГОСТ 19.101 — общие требования к программной документации (структура, реквизиты, оформление).
- ГОСТ 19.104 — основной набор документов, входящих в состав ПО.
- ГОСТ 19.102 — классификация программных документов по стадиям ЖЦ и ролям.
- ГОСТ 19.103 — ведомость программных документов.
- ГОСТ 19.201 — пояснительная записка
- ГОСТ 19.301 — программа и методика испытаний
- ГОСТ 19.402 — структура программы
- ГОСТ 19.503 — входные и выходные данные
- ГОСТ 19.505/506 — руководства пользователя и администратора
- ГОСТ 19.502 — протокол взаимодействия
- ГОСТ 19.701 — формуляр программы, используется при регистрации ПО.
ГОСТ 19 актуален для формализации внутренних модулей, пользовательских инструкций и проектной части программного обеспечения.
Международные стандарты: ISO и IEEE
Наряду с российскими ГОСТами, мы в Etence ориентируемся на международные стандарты проектирования и сопровождения ПО:
ISO/IEC 25010 – качество программного обеспечения: надёжность, безопасность, удобство и др.
ISO/IEC/IEEE 29119 — стандарты на тестирование ПО (Test Plan, Test Case, Reporting).
ISO/IEC 27001/27034 — безопасность и безопасность приложений, полезны при работе с защищаемой информацией.
ISO/IEC 12207 — жизненный цикл программных систем, включая процессы разработки, сопровождения и оценки;
ISO/IEC/IEEE 42010 — описание архитектуры программных и системных решений;
IEEE 1016 — стандарты описания дизайна программного обеспечения (Software Design Description);
SBOM и IETF — международные подходы к управлению сторонними компонентами и зависимостями.
Эти стандарты особенно важны при работе с интеграцией в сложные экосистемы, формализации архитектуры и построении устойчивых процессов разработки.
Подробнее о соответствии между ГОСТ и международными подходами — в статье
Сопоставление ГОСТ и ISO: как унифицировать проектную документацию.
Внутренняя структура документации в Etence опирается на ГОСТ 34 как основу стадий, ГОСТ 19 — как основу содержания документов, и ISO/IEEE — как расширение для современных требований безопасности, архитектуры и DevOps.
В Etence мы также выделяем уровни фиксации архитектуры — от идеи до реализации и сопровождения. Это позволяет адаптировать глубину документации под контекст проекта.
Что это даёт бизнесу
- Управляемость — система не теряется при смене участников.
- Повторяемость — можно воспроизвести или масштабировать решение.
- Прозрачность — понятна логика решений и распределение ответственности.
- Готовность к сертификации — наличие всех необходимых артефактов.
Что дальше
Если вы хотите внедрить или пересобрать структуру проектной документации:
- мы поможем адаптировать состав под ваш проект;
- предоставим шаблоны и рекомендации;
- поддержим команду при внедрении и сопровождении.
Свяжитесь с нами, чтобы сделать документацию источником устойчивости, а не барьером для развития.
06.05.2025