Оформление программной документации по ГОСТ: чек-лист перед передачей

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

Чек-лист ниже подходит для документов по ГОСТ 19, ГОСТ 34 и смешанных комплектов, где стандарты используются как режим оформления и проверки.

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

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

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

Оформление по ГОСТ проверяют не только по титульному листу. Важно, чтобы названия, ссылки, приложения и перечни одинаково читались во всем комплекте.

Caps, кавычки, подзаголовки и обозначения выбирают один раз для всего комплекта. Если один документ называется «Описание программы», а другой ссылается на него как «описание структуры» или «архитектура ПО», приемка начинает проверять не только содержание, но и расхождения в названиях.

Приложение может быть частью документа или отдельным файлом. Это разные режимы оформления и передачи.

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

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

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