Подготовка документации на программные средства

Содержание:

Введение стр.2

1.Программный продукт стр.3

1. 1. Понятие программного продукта стр.3

1. 2.Основные вопросы при разработке программных средств стр.3

2.Программная документация стр.4

2.1.Содержание и сфера применения Единой системы программной документации (ЕСПД). стр.5

2.2.Краткое представление стандартов ЕСПД стр.5-8

2.3. Типы технической документации на программный продукт стр.13

3.Разработка документации программных средств. стр.14-19

Заключение стр.20

ВВЕДЕНИЕ

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

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

1. Программный продукт.

1.1.Понятие программного продукта.

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

- программа в состоянии нормально функционировать не только на компьютере у автора, а в рамках любой подходящей системы;

- автор (или иной правообладатель) на определенных условиях позволяет распространять и использовать программу;

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

1.2.Основные вопросы при разработке программных средств

Когда программист-разработчик получает в той или иной форме задание на программирование, перед ним, перед руководителем проекта и перед всей проектной группой встают вопросы:

что должно быть сделано, кроме собственно программы?

что и как должно быть оформлено в виде документации?

что передавать пользователям, а что службе сопровождения?

как управлять всем этим процессом?

что должно входить в само задание на программирование?

Кроме упомянутых вопросов есть и другие.

На эти и массу других вопросов когда-то отвечали государственные стандарты на программную документацию - комплекс стандартов 19-й серии ГОСТ ЕСПД. Но уже тогда у программистов была масса претензий к этим стандартам. Что-то требовалось дублировать в документации много раз (как, казалось — неоправданно), а многое не было предусмотрено, как, например, отражение специфики документирования программ, работающих с интегрированной базой данных.

2.Программная документация.

2.1.Содержание и сфера применения Единой системы программной документации (ЕСПД).

Единая система программной документации (ЕСПД) — отечественный комплекс стандартов на программную документацию. В профессиональном просторечии его еще называют «девятнадцатым гостом», что не совсем правильно, поскольку речь идет не об одном, а примерно о 30 разных нормативно-технических документах.

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

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

Стандарты ЕСПД были приняты в конце 70-х годов и дошли до нас в виде, близком к первоначальному. В них отражена практика работы ведомственных вычислительных центров, где эксплуатировались большие ЭВМ.

Формально «девятнадцатому» есть современная альтернатива. Переведены на русский язык и приняты в России на правах национальных некоторые стандарты ИСО/МЭК в области системной и программной инженерии. Но крупные, в том числе, государственные заказчики переходить на них не торопятся.

Каждый стандарт ЕСПД при небольшом (страницы три максимум) объеме представляет собой набор довольно формальных и поэтому легко проверяемых требований к документу или к комплекту документации. Строго говоря, это не мешает разработчику документации писать правильно оформленные глупости. Но поскольку ЕСПД четко определяет, из чего должен состоять и как должен выглядеть результат, мы можем, по крайней мере, сразу отклонить пачку бумаги, которая в эти рамки не вписывается. Что существенно упрощает задачу сдачи-приемки документации как для заказчика, так и для исполнителя.

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

2.2. Краткое представление стандартов ЕСПД.

До пересмотра всего комплекса, многие стандарты ЕСПД могут с пользой применяться в практике документирования ПС. Эта позиция основана на следующем:

стандарты ЕСПД вносят элемент упорядочения в процесс документирования ПС;

предусмотренный стандартами ЕСПД состав программных документов вовсе не такой "жесткий", как некоторым кажется: стандарты позволяют вносить в комплект документации на ПС дополнительные виды

стандарты ЕСПД позволяют вдобавок мобильно изменять структуры и содержание установленных видов ПД исходя из требований заказчика и пользователя.

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

Стандарты ЕСПД (как и другие ГОСТы) подразделяют на группы, приведенные в таблице:

Kод группы Наименование группы

0 Общие положения

1 Основополагающие стандарты

2 Правила выполнения документации разработки

3 Правила выполнения документации изготовления

4 Правила выполнения документации сопровождения

5 Правила выполнения эксплуатационной документации

6 Правила обращения программной документации

7 Резервные группы

8 Резервные группы

9 Прочие стандарты

Обозначение стандарта ЕСПД должно состоять из:

числа 19 (присвоенных классу стандартов ЕСПД);

одной цифры (после точки), обозначающей код классификационной группы стандартов, указанной таблице;

двузначного числа (после тире), указывающего год регистрации стандарта.

Состав нормативно-технических документов:

ГОСТ 19.001-77 Единая система программной документации.

Общие положения

ГОСТ 19.002-80 Единая система программной документации.

Схемы алгоритмов и программ. Правила выполнения

ГОСТ 19.004-80 Единая система программной документации.

Термины и определения

ГОСТ 19.005-85 Единая система программной документации.

Р-схемы алгоритмов и программ. Обозначения условные графические и правила выполнения

ГОСТ 19.101-77 Единая система программной документации.

Виды программ и программных документов

ГОСТ 19.102-77 Единая система программной документации.

Стадии разработки

ГОСТ 19.103-77 Единая система программной документации.

Обозначение программ и программных документов

ГОСТ 19.104-78 Единая система программной документации.

Основные надписи

ГОСТ 19 105-78 Единая система программной документации.

Общие требования к программным документам

ГОСТ 19.106-78 Единая система программной документации.

Требования к программным документам, выполненным печатным способом

ГОСТ 19.201-78 Единая система программной документации.

Техническое задание. Требования к содержанию и оформлению

ГОСТ 19.202-78 Единая система программной документации.

Спецификация. Требования к содержанию и оформлению

ГОСТ 19.301-79 Единая система программной документации.

Программа и методика испытаний. Требования к содержанию и оформлению

ГОСТ 19.401-78 Единая система программной документации.

Текст программы. Требования к содержанию и оформлению

ГОСТ 19.402-78 Единая система программной документации.

Описание программы

ГОСТ 19 403-79 Единая система программной документации.

Ведомость держателей подлинников

ГОСТ 19.404-79 Единая система программной документации.

Пояснительная записка. Требования к содержанию и оформлению

ГОСТ 19.501-78 Единая система программной документации.

Формуляр. Требования к содержанию и оформлению

ГОСТ 19.502-78 Единая система программной документации.

Описание применения. Требования к содержанию и оформлению

ГОСТ 19.503-79 Единая система программной документации.

Руководство системного программиста. Требования к содержанию и оформлению

ГОСТ 19.504-79 Единая система программной документации.

Руководство программиста. Требования к содержанию и оформлению

ГОСТ 19.505-79 Единая система программной документации.

Руководство оператора. Требования к содержанию и оформлению

ГОСТ 19.506-79 Единая система программной документации.

Описание языка. Требования к содержанию и оформлению

ГОСТ 19.507-79 Единая система программной документации.

Ведомость эксплуатационных документов

ГОСТ 19.508-79 Единая система программной документации.

Руководство по техническому обслуживанию. Требования к содержанию и оформлению

ГОСТ 19.601-78 Единая система программной документации.

Общие правила дублирования, учета и хранения

ГОСТ 19.602-78 Единая система программной документации.

Правила дублирования, учета и хранения программных документов, выполненных печатным способом

ГОСТ 19.603-78 Единая система программной документации.

Общие правила внесения изменений

ГОСТ 19.604-78 Единая система программной документации.

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

Из всех стандартов ЕСПД остановимся только на тех, которые могут чаще использоваться на практике.

Первым укажем стандарт, который можно использовать при формировании заданий на программирование.

ГОСТ (СТ СЭВ) 19.201-78 (1626-79). ЕСПД. Техническое задание. Требование к содержанию и оформлению. (Переиздан в ноябре 1987г с изм.1).

Техническое задание (ТЗ) содержит совокупность требований к ПС и может использоваться как критерий проверки и приемки разработанной программы. Поэтому достаточно полно составленное (с учетом возможности внесения дополнительных разделов) и принятое заказчиком и разработчиком, ТЗ является одним из основополагающих документов проекта ПС.

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

- введение;

- основания для разработки;

- назначение разработки;

- требования к программе или программному изделию;

- требования к программной документации;

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

- стадии и этапы разработки;

- порядок контроля и приемки;

- в техническое задание допускается включать приложения.

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

Следующий стандарт

ГОСТ (СТ СЭВ) 19.101-77 (1626-79). ЕСПД. Виды программ и программных документов (Переиздан в ноябре 1987г с изм.1).

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

Виды программ

1. Компонент Программа, рассматриваемая как единое целое, выполняющая законченную функцию и применяемая самостоятельно или в составе комплекса

2. Комплекс Программа, состоящая из двух или более компонентов и (или) комплексов, выполняющих взаимосвязанные функции, и применяемая самостоятельно или в составе другого комплекса

Виды программных документов

К программным относят документы, содержащие сведения, необходимые для разработки, сопровождения и эксплуатации программного обеспечения. Документирование программною обеспечения осуществляется в соответствии с Единой системой программной документации (ГОСТ 19.XXX). Так ГОСТ 19.101-77 устанавливает виды программных документов для программного обеспечения различных типов. Ниже перечислены основные программные документы по этому стандарту и указано, какую информацию они должны содержать.

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

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

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