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

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

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

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

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

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

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

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

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

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

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

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

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

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