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

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

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

ГОСТ 34, ГОСТ 19, ISO/IEC и IEEE лучше использовать как режимы оформления и проверки, а не как самоцель. Сначала нужно понять, какие риски закрывает документ: неверную оценку, спорную приемку, потерю знаний, ошибку интеграции, сложность эксплуатации или невозможность передать проект другой команде.

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

• перед оценкой разработки, когда нужно понять состав артефактов и границы работ;
• для проекта с интеграциями, несколькими ролями, регуляторными требованиями или формальной приемкой;
• когда результат должен перейти в поддержку, эксплуатацию или к другой команде;
• если договор, закупка или внутренний контроль требуют комплект проектной, программной или эксплуатационной документации;
• когда нужно совместить практичные agile-артефакты с ГОСТ 34, ГОСТ 19, ISO/IEC или IEEE.

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

Не стоит начинать с копирования перечня стандартов. Если документ не помогает принять решение, проверить результат или передать знания, его нужно сократить или объединить с другим артефактом.

• цель системы, границы проекта и ожидаемый результат;
• реестр требований, открытых вопросов и ограничений;
• роли пользователей, внешние системы, интеграции и данные;
• нефункциональные требования: безопасность, производительность, доступность, аудит, хранение данных;
• условия приемки, эксплуатации и сопровождения;
• договорные или закупочные требования к составу документации;
• требования к формату: ГОСТ 34, ГОСТ 19, ISO/IEC, IEEE или внутренние шаблоны.

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

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

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

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

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

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

Удобно не спорить о «полном» комплекте абстрактно, а выбрать уровень документации под риск проекта.

1. Определить, кто будет читать и использовать документ.
2. Связать каждый документ с проектным риском или этапом приемки.
3. Проверить, какие документы прямо требуются договором, закупкой или регуляторикой.
4. Убрать дубли: не заводить отдельный документ, если смысл уже закрыт в ТЗ, архитектурном описании или инструкции.
5. Согласовать формат, владельца, срок обновления и место хранения.
6. Перед передачей проверить комплектность по требованиям, коду, сборке, инфраструктуре и эксплуатации.

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

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

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

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