Нормативная база в области документирования ПС

что должно быть сделано, кроме собственно программы?
что и как должно быть оформлено в виде документации?
что передавать пользователям, а что — службе сопровождения?
управлять всем этим процессом?
что должно входить в само задание на программирование?

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

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

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

Стандарты ЕСПД подразделяют на группы

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

Виды программных документов
ГОСТ 19.101-77

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

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

Виды программных документов
Программа и методика испытаний - требования, подлежащие проверке при испытании программы, а также порядок и методы их контроля
Техническое задание - назначение и область применения программы, технические, технико-экономические и специальные требования, предъявляемые к программе, необходимые стадии и сроки разработки, виды испытаний
Пояснительная записка - схема алгоритма, общее описание алгоритма и (или) функционирования программы, а также обоснование принятых технических и технико-экономических решений
Эксплуатационные документы - сведения для обеспечения функционирования и эксплуатации программы

Виды эксплуатационных документов
Ведомость эксплуатационных документов
Формуляр
Описание применения
Руководство системного программиста
Руководство программиста
Руководство оператора
Описание языка
Руководство по техническому обслуживанию

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

Расположение материалов программного документа
Программный документ
Титульная часть
Часть регистрации изменений

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

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

Построение документа
При необходимости допускается делить документ на части
Аннотацию размещают на отдельных страницах, снабжают заголовком "АННОТАЦИЯ", нумеруют и включают в содержание документа
Содержание документа размещают на отдельной странице, снабжают заголовком "СОДЕРЖАНИЕ" и включают в общее количество страниц документа
Текст каждого документа, при необходимости, разбивается на пункты, а пункты - на подпункты
Заголовки разделов пишут прописными буквами и размещают симметрично относительно правой и левой границ текста
Разделы, подразделы, пункты и подпункты следует нумеровать арабскими цифрами с точкой

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

Пример сноски

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

Пример иллюстрации

Формулы
Формулы в документе, если их более одной, нумеруются арабскими цифрами, номер ставят с правой стороны страницы, в скобках на уровне формулы.
В пределах всего документа или его частей, в случае деления документа на части, формулы имеют сквозную нумерацию
Ссылки в тексте на порядковый номер формулы дают в скобках, например: "в формуле (3)"
При делении документа на части номер части ставится перед порядковым номером формулы и отделяется от последней точкой, например: "в формуле (1.4)"
Значение символов, входящих в формулу, должны быть приведены непосредственно под формулой. Значение каждого символа печатают с новой строки в той последовательности, в какой они приведены в формуле. Первая строка расшифровки должна начинаться со слова "где", без двоеточия после него

Пример формулы

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

Примечания
В примечаниях к тексту и таблицам указывают только справочные и пояснительные данные
Одно примечание не нумеруется. После слова "Примечание" ставят точку
Несколько примечаний следует нумеровать по порядку арабскими цифрами с точкой
После слова "Примечания" ставят двоеточие
Текст примечаний допускается печатать только через один интервал

Пример примечания
П р и м е ч а н и е . _________________________________
или
П р и м е ч а н и я:
1. __________________________________________________
2. __________________________________________________

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

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

Вопросы для самопроверки
Дайте определение понятиям «Компонент» и «Комплекс».
Перечислите виды программных документов.
Что входит в титульную часть программного документа?
Как оформляется сноска?
Как оформляются иллюстрации?
Как оформляются формулы?
Как оформляются примечания?
Можно ли использовать сокращения в тексте и надписях под иллюстрациями?

Основные надписи
ГОСТ 19.104-78

Форма титульного листа
поле 1 - наименование ведомства или министерства, в систему которого входит организация;
поле 2 - в левой части от заказчика, в правой части от разработчика;
поле 3 - полное наименование;
поле 4 - обозначение документа и указание вида носителя данных;
поле 5 - указывают объем документа;
поле 6 - должности и подписи руководителя организации;
поле 7 - год издания (утверждения) документа (без указания слова «год» или «г»);
поле 8 - отметка об учете и хранении;
поле 9 - строка изменений;
поле 10 - литера документа.

Руководство Оператора
ГОСТ 19.505-79

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

Типовая структура
Назначение программы.
Условия выполнения программы.
Выполнение программы.
Сообщения оператору.