Документирование программных систем

Составление программной документации – очень важный этап жизненного цикла программной системы.

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

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

Документация на программную систему составляется в соответствии со стандартами ЕСПД (группа стандартов - ГОСТы 19.ХХХ).

В соответствии с данными стандартами должны оформляться следующие программные документы.

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

Ведомость держателей подлинников (код вида документа – 05) должна содержать список предприятий, на которых хранятся подлинники программных документов.

Текст программы (код вида документа – 12) должен содержать текст программы с необходимыми комментариями.

Описание программы (код вида документа – 13) должно содержать сведения о логической структуре и функционировании программы.

Ведомость эксплуатационных документов (код вида документа – 20) должна содержать перечень эксплуатационных документов на программу, к которым относятся документы с кодами 30, 31, 32, 33, 34, 35, 46.

Формуляр (код вида документа – 30) должен содержать основные характеристики программного обеспечения, комплектность и сведения об эксплуатации программы.

Описание применения (код вида документа – 31) должно содержать сведения о назначении программного обеспечения, области применения, применяемых методах, класс решаемых задач, ограничениях для применения, минимальной конфигурации технических средств.

Руководство системного программиста (код вида документа – 32) должно содержать сведения для проверки, обеспечения функционирования и настройки программы на условия конкретного применения.

Руководство программиста (код вида документа – 33) должно содержать сведения для эксплуатации программного обеспечения.

Руководство оператора (код вида документа – 34) должно содержать сведения для обеспечения процедуры общения оператора с вычислительной системой в процессе выполнения программного обеспечения.

Описание языка (код вида документа – 35) должно содержать описание синтаксиса и семантики языка.

Руководство по техническому обслуживанию (код вида документа – 46) должно содержать сведения для применения тестовых и диагностических программ при обслуживании технических средств.

Программа и методика испытаний (код вида документа – 51) должны содержать требования, подлежащие проверке при испытании программного обеспечения, а также порядок и методы их контроля.

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

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

Пояснительная записка должна включать следующие разделы:

– введение;

– назначение и область применения;

– технические характеристики;

– ожидаемые технико-экономические показатели;

– источники, используемые при разработке.

В разделе Введение указывают наименование программы и документа, на основании которого ведется разработка.

В разделе Назначение и область применения указывают назначение программы и дают краткую характеристику области применения.

Раздел Технические характеристики должен содержать следующие подразделы:

– постановку задачи, описание применяемых математических методов и допущений и ограничений, связанных с выбранным математическим аппаратом;

– описание алгоритмов и функционирования программы с обоснованием принятых решений;

– описание и обоснование выбора способа организации входных и выходных данных;

– описание и обоснование выбора состава технических и программных средств на основании проведенных расчетов или анализов.

В разделе Ожидаемые технико-экономические показатели указывают технико-экономические показатели, обосновывающие преимущество выбранного варианта технического решения.

В разделе Источники, использованные при разработке, указывают перечень научно-технических публикаций, нормативно-технических документов и других научно-технических материалов.

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

Руководство пользователя, как правило, содержит следующие разделы:

– общие сведения о программном продукте;

– описание установки;

– описание запуска;

– инструкции по работе (или описание пользовательского интерфейса);

– сообщения пользователю.

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

Раздел Установка обычно содержит подробное описание действий по установке программного продукта и сообщений, которые при этом могут быть получены.

В разделе Запуск, как правило, описаны действия по запуску программного продукта и сообщения, которые при этом могут быть получены.

Раздел Инструкции по работе обычно содержит описание режимов работы, форматов ввода-вывода информации и возможных настроек.

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