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

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

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

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

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

• Требования и область работ. Что должна делать система и что входит в текущий этап.
• Проектные решения. Архитектура, состав компонентов, интеграции, ограничения.
• Документы программного компонента. Назначение, описание программы, состав программных средств.
• Поставка и приемка. Листинг, changelog, перечень доработок, критерии проверки.
• Эксплуатация. Инструкции, регламенты, доступы, правила поддержки.

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

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

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

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