Документирование программного обеспечения

Документирование ПО

Содержание

• О документации
• О стандартах
• Стандарт ЕСПД
• Стандарты ГОСТ Р
• Руководство пользователя
• Литература

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

Программную документацию по отношению к пользователю делят:

• Внутренняя (технологическая) – используется в процессе разработки ПО и недоступна пользователю;
• Внешняя (пользовательская) – всевозможные руководства для пользователя.

Стандарт документирования

ГОСТ при разработке программных продуктов дает возможность:

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

Стандарт документирования

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

Значение ЕСПД

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

Недостатки ЕСПД

• ориентацию на единственную, «каскадную» модель жизненного цикла (ЖЦ) ПС;
• отсутствие четких рекомендаций по документированию характеристик качества ПС;
• отсутствие системной увязки с другими действующими отечественными системами стандартов по ЖЦ и документированию продукции в целом, например, СРПП и ЕСКД;

Недостатки ЕСПД

• нечетко выраженный подход к документированию ПС как товарной продукции;
• отсутствие рекомендаций по самодокументированию ПС, например, в виде экранных меню и средств оперативной помощи пользователю («хелпов»);
• отсутствие рекомендаций по составу, содержанию и оформлению перспективных документов на ПС, согласованных с рекомендациями международных и региональных стандартов.

Стандарты ЕСПД

• В соответствии с Законом РФ «О стандартизации» стандарты ЕСПД становятся обязательными на контрактной основе — то есть при ссылке на них в договоре на разработку (поставку) ПС.

Группы стандарта ЕСПД

Kод группы

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

0

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

1

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

2

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

3

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

4

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

5

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

6

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

Обозначение стандарта ЕСПД ГОСТ

19.ХХХ – ХХ должно состоять из

• числа 19 (присвоенных классу стандартов ЕСПД);
• одной цифры (после точки), обозначающей код классификационной группы стандартов, указанной в таблице;
• двузначного числа (после тире), указывающего год регистрации стандарта.

Перечень документов ЕСПД

• ГОСТ 19.001-77 ЕСПД. Общие положения.
• ГОСТ 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.404-79 ЕСПД. Пояснительная записка. Требования к содержанию и оформлению.
• ГОСТ 19.501-78 ЕСПД. Формуляр. Требования к содержанию и оформлению.
• ГОСТ 19.502-78 ЕСПД. Описание применения. Требования к содержанию и оформлению.

Перечень документов ЕСПД

• ГОСТ 19.503-79 ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению.
• ГОСТ 19.504-79 ЕСПД. Руководство программиста.
• ГОСТ 19.505-79 ЕСПД. Руководство оператора.
• ГОСТ 19.506-79 ЕСПД. Описание языка.

Перечень документов ЕСПД

• ГОСТ 19.508-79 ЕСПД. Руководство по техническому обслуживанию. Требования к содержанию и оформлению.
• ГОСТ 19.604-78 ЕСПД. Правила внесения изменений в программные документы, выполняемые печатным способом.
• ГОСТ 19.701-90 ЕСПД. Схемы алгоритмов, программ, данных и систем. Условные обозначения и правила выполнения.
• ГОСТ 19.781-90. Обеспечение систем обработки информации программное.

Перечень документации, декларируемой ГОСТ 19.105-78:

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

1.1. Спецификация – состав программы и документации на нее. 1.2. Ведомость держателей подлинников – перечень предприятий, на которых хранятся подлинники программной документации. 1.3. Текст программы – запись текста программы с необходимыми комментариями. 1.4. Описание программы – сведения о логической и функциональной структуре программы.

Перечень документации, декларируемой ГОСТ 19.105-78:

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

1.5. Программа и методика испытаний – требования, подлежащие проверке при испытании программы, порядок и методы их контроля. 1.6. Техническое задание – назначение и область применения программы, технические и специальные требования, необходимые стадии и сроки разработки, виды испытаний. 1.7. Пояснительная записка – схема алгоритма, общее описания алгоритма, выполняемая программой функция. Объяснение принятых технических решений.

Перечень документации, декларируемой ГОСТ 19.105-78:

• Документы, используемые при эксплуатации программного продукта. 2.1.Ведомость эксплуатационных документов – перечень эксплуатационных документов на программу. 2.2.Формуляр – основные характеристики программы, комплектность, общие сведения об эксплуатации программы. 2.3.Описание применения – сведения о назначении программы, области применения, классе решаемых задач, ограничения на применение, необходимая конфигурация технических средств. 2.4.Руководство системного программиста – сведения для проверки и обеспечения функциональности, настройки программы.

Перечень документации, декларируемой ГОСТ 19.105-78:

• Документы, используемые при эксплуатации программного продукта. 2.5.Руководство программиста – сведения для эксплуатации настроенной программы. 2.6.Руководство оператора – сведения для обеспечения процедуры общения оператора с ЭВМ в процессе выполнения программы. 2.7.Описание языка – описание синтаксиса и семантики языка, используемого в программе. 2.8.Руководство по техническому обслуживанию – сведения для применения тестовых программ при обслуживании технических средств.

ГОСТ 19.106-78 ЕСПД. Требования к программным документам, выполненным печатным способом. Состав программного документа

• титульная часть:

• лист утверждения (не входит в общее количество листов документа);
• титульный лист (первый лист документа);

• информационная часть:

• аннотация;
• лист содержания;

Состав программного документа

• основная часть:

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

• часть регистрации изменений:

• лист регистрации изменений

Стандарты документирования

• ГОСТ 19781-90 Обеспечение систем обработки информации программное. Термины и определения. Разработан взамен ГОСТ 19781-83 и ГОСТ 19.004-80 и устанавливает термины и определения понятий в области программного обеспечения (ПО) систем обработки данных (СОД), применяемые во всех видах документации и литературы, входящих в сферу работ по стандартизации или использующих результаты этих работ.
• ГОСТ 28388-89 Системы обработки информации. Документы на магнитных носителях данных. Порядок выполнения и обращения. Распространяется не только на программные, но и на конструкторские, технологические и другие проектные документы, выполняемые на магнитных носителях.

Государственные стандарты РФ ( ГОСТ Р)

• ГОСТ Р ИСО/МЭК 9294-93 Информационная технология. Руководство по управлению документированием программного обеспечения.

Стандарт полностью соответствует международному стандарту ИСО/МЭК ТО 9294:1990 и устанавливает рекомендации по эффективному управлению документированием ПС для руководителей, отвечающих за их создание. Целью стандарта является оказание помощи

• в определении стратегии документирования ПС; выборе стандартов по документированию; выборе процедур документирования; определении необходимых ресурсов; с оставлении планов документирования.
• в определении стратегии документирования ПС;
• выборе стандартов по документированию;
• выборе процедур документирования;
• определении необходимых ресурсов; с
• оставлении планов документирования.

Государственные стандарты РФ ( ГОСТ Р)

• ГОСТ Р ИСО 9127-94 Системы обработки информации. Документация пользователя и информация на упаковке для потребительских программных пакетов.

Стандарт полностью соответствует международному стандарту ИСО 9127:1989. В контексте настоящего стандарта

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

Руководство пользователя

• Введение

• Область применения Краткое описание возможностей Требования к уровню подготовки пользователя Перечень эксплуатационных документов, с которыми необходимо ознакомиться пользователю
• Область применения
• Краткое описание возможностей
• Требования к уровню подготовки пользователя
• Перечень эксплуатационных документов, с которыми необходимо ознакомиться пользователю

Руководство пользователя

• Назначение и условия применения

• Виды деятельности и функции для автоматизации которых предназначено данное ПС Условия, при соблюдении которых обеспечивается применение ПС в соответствии с назначением
• Виды деятельности и функции для автоматизации которых предназначено данное ПС
• Условия, при соблюдении которых обеспечивается применение ПС в соответствии с назначением

Руководство пользователя

• Подготовка к работе

• Состав и содержание дистрибутивного носителя данных Порядок загрузки данных и программ Порядок контроля и проверки работоспособности
• Состав и содержание дистрибутивного носителя данных
• Порядок загрузки данных и программ
• Порядок контроля и проверки работоспособности

Руководство пользователя

• Описание операций - для каждой операции обработки данных должно быть указано

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

Руководство пользователя

• Аварийные ситуации

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

Литература

• Гусятников В.Н., Безруков А.И. Стандартизация и разработка программных систем. - М: Финансы и статистика, 2010.
• Гагарина Л.Г., Кокорева Е.В., Виснадул Б.Д. Технология разработки программного обеспечения.- М: ИД «ФОРУМ»: ИНФРА-М, 2008
• Благодатских В.А., Волнин В.А., Поскакалов К.Ф. Стандартизация разработки программных средств. – М: Финансы и статистика, 2003