Создание документации для информационных систем по ГОСТ 34 и ГОСТ 19

В современном мире каждый день появляется десятки и сотни различных программ, приложений, информационных систем. Они могут быть разработаны как для государственного или коммерческого сектора, так и для обычных пользователей. 90% всех пользователей не читает документацию, считает её скучной, занудной и неинтересной, а открывает руководство пользователя только тогда, когда что-то не получается или разобраться без инструкции уж совсем невозможно. Общепринято теперь строить пользовательский интерфейс таким образом, чтобы он был интуитивно понятен, и пользователь мог разобраться с системой, не прибегая к чтению длиннейших мануалов. Однако, при работе с крупными заказчиками практически всегда необходимо сдать определённый пакет документов – руководств, инструкций, проектных решений, оформленных по ГОСТу.

Введение

В современном мире каждый день появляется десятки и сотни различных программ, приложений, информационных систем. Они могут быть разработаны как для государственного или коммерческого сектора, так и для обычных пользователей. 90% всех пользователей не читает документацию, считает её скучной, занудной и неинтересной, а открывает руководство пользователя только тогда, когда что-то не получается или разобраться без инструкции уж совсем невозможно. Общепринято теперь строить пользовательский интерфейс таким образом, чтобы он был интуитивно понятен, и пользователь мог разобраться с системой, не прибегая к чтению длиннейших мануалов. Однако, при работе с крупными заказчиками практически всегда необходимо сдать определённый пакет документов – руководств, инструкций, проектных решений, оформленных по ГОСТу.
Когда впервые сталкиваешься с написанием документации по ГОСТу, то приходишь в ступор и полный шок, так как этих ГОСТов «море» и, как и чего по ним писать становится неясно.
В этой статье рассмотрены ГОСТы для написания документации и их основные моменты.

Какие бывают ГОСТы?

Для начала надо разобраться какие бывают ГОСТы. Все лишь знают, что ГОСТ — это нечто, что разрабатывалось при Союзе и их просто бесконечное количество. Спешу вас успокоить для сферы IT ГОСТов не так много, и они все, несмотря на свой срок создания, не потеряли своей актуальности.
В первую очередь стандарты для написания документации делятся на два типа:

  1. Международные стандарты (ISO, IEEE Std);
  2. Российские или Советские ГОСТы.

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

  1. IEEE Std 1063-2001 «IEEE Standard for Software User Documentation» — стандарт для написания руководства пользователя;
  2. IEEE Std 1016-1998 «IEEE Recommended Practice for Software Design Descriptions» — стандарт для написания технического описания программы;
  3. ISO/IEC FDIS 18019:2004 «Guidelines for the design and preparation of user documentation for application software» — ещё один стандарт для написания руководства пользователя. В данном документе есть большое количество примеров. Так сказать, это больше похоже на руководство по написанию руководства пользователя. Начинающим специалистам будет особенно полезен;
  4. ISO/IEC 26514:2008 «Requirements for designers and developers of user documentation» — ещё один стандарт для дизайнеров и разработчиков пользователей документации.

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

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

Чем отличаются ГОСТы серий 19 и 34?

Первый вопрос, который возникает, а чем, вообще, эти ГОСТы 19 и 34 отличаются друг от друга.
В ГОСТе 19.781-90 «Единая система программной документации. Программное обеспечение систем обраб0отки информации. Термины и определения» указаны определения:

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

В ГОСТе 34.003-90 «Информационная технология. Комплекс стандартов на автоматизированные системы. Автоматизированные системы. Термины и определения» указано определение:

  1. Автоматизированная система (АС) — система, состоящая из персонала и комплекса средств автоматизации его деятельности, реализующая информационную технологию выполнения установленных функций.
    В зависимости от вида деятельности выделяют, например, следующие виды АС: автоматизированные системы управления (АСУ), системы автоматизированного проектирования (САПР), автоматизированные системы научных исследований (АСНИ) и другие.

В зависимости от вида управляемого объекта (процесса) АСУ делят, например, на: АСУ технологическими процессами (АСУТП), АСУ предприятиями (АСУП) и т.д.
Также ГОСТ 34 делает разделение на виды обеспечения АС:

  1. Организационное;
  2. Методическое;
  3. Техническое;
  4. Математическое;
  5. Программное обеспечение;
  6. Информационное;
  7. Лингвистическое;
  8. Правовое;
  9. Эргономическое.

В итоге Автоматизированная система — это не программа, а комплекс видов обеспечения, среди которых есть и программное обеспечение. АС, как правило, несёт в себе организационное решение под конкретного пользователя и заказчика, а Программа может быть создана и растиражирована под большое количество пользователей без привязки к какому-либо предприятию.
Поэтому если вы разрабатываете документацию на программу, которую создали под конкретное предприятие, то ваш ГОСТ 34. Если же пишете документы на массовую программу, то ваш ГОСТ 19.

ГОСТ 34

Серия ГОСТов 34 (ГОСТ 34.ххх Стандарты информационной технологии) состоит:

  1. ГОСТ 34.201-89 Виды, комплектность и обозначения документов при создании автоматизированных систем — данный стандарт устанавливает виды, наименование, комплектность и номера документов. Является одним из основных документов серии ГОСТов 34. По сути, это базовый документ, так что новичкам необходимо ознакомиться с ним в первую очередь.
  2. ГОСТ 34.320-96 Концепции и терминология для концептуальной схемы и информационной базы — настоящий стандарт устанавливает основные понятия и термины концептуальных схем и информационных баз, охватывающие разработку, описание и применение концептуальных схем и информационных баз, манипулирования информацией, а также описание и реализацию информационного процесса. Стандарт определяет роль концептуальной схемы. Положения, изложенные в нём, носят рекомендательный характер и могут использоваться для оценки систем управления базами данных (СУБД). Этот документ не описывает конкретные методы применения средств поддержки концептуальных схем. Описанные в стандарте языки концептуальных схем не следует рассматривать как стандартные.
  3. ГОСТ 34.321-96 Информационные технологии. Система стандартов по базам данных. Эталонная модель управления — данный документ устанавливает эталонную модель управления данными.
    Эталонная модель определяет общую терминологию и понятия, относящиеся к данным информационных систем. Такие понятия используются для определения услуг, предоставляемых системами управления базами данных или системами словарей данных.
    Эталонная модель не рассматривает протоколы для управления данными.
    Область применения эталонной модели включает процессы, которые касаются управления постоянными данными и их взаимодействия с процессами, отличающимися от требований конкретной информационной системы, а также общие услуги управления данными, для определения, хранения, поиска, обновления, ввода, копирования, восстановления и передачи данных.
  4. ГОСТ 34.601-90 Автоматизированные системы. Стадии создания — стандарт устанавливает стадии и этапы создания АС.
  5. ГОСТ 34.602-89 Техническое задание на создание автоматизированной системы (Взамен ГОСТ 24.201-85) — устанавливает состав, содержание, правила оформления документа «Техническое задание на создание (развитие или модернизацию) системы».
    Данный документ является одним из часто используемых документов серии ГОСТ 34. При разработке ТЗ по этому ГОСТу следует помнить и о других стандартах, даже если в этом документе нет ссылок на эти стандарты.
  6. ГОСТ 34.603-92 Информационная технология. Виды испытаний автоматизированных систем — стандарт устанавливает виды испытаний АС автономные, комплексные, приёмочные испытаний и опытная эксплуатация) и общие требования к их проведению.
  7. РД 50-34.698-90 Автоматизированные системы. Требования к содержанию документов — один из важнейших документов 34 ГОСТа, так как именно в нём описано содержание практически всех документов, а также описание каждого пункта документа.
  8. ГОСТ Р ИСО/МЭК 8824-3-2002 Информационная технология. Абстрактная синтаксическая нотация версии один — настоящий стандарт является частью абстрактной синтаксической нотации версии 1 (АСН.1) и устанавливает нотацию для спецификации ограничений, определённых пользователем, и табличных ограничений.
  9. ГОСТ Р ИСО/МЭК 10746-3-2001 Управление данными и открытая распределённая обработка.
    В настоящем стандарте:

    • определено, как специфицируются системы открытой распределённой обработки (ОРО) с использованием понятий, введённых в ГОСТ Р ИСО/МЭК 10746-2;
    • идентифицированы характеристики, по которым системы относятся к системам ОРО.

    В стандарте установлен каркас для координации разработки стандартов по системам ОРО.

  10. ГОСТ Р ИСО/МЭК 15271-02 Процессы жизненного цикла программных средств — данный ГОСТ необходимо больше, на мой взгляд, для аналитиков при проектировании и моделировании АС.
    Этот документ полезен, с моей точки зрения, в чисто образовательных целях.
  11. ГОСТ Р ИСО/МЭК 15910-2002 Процесс создания документации пользователя программного средства — определяет минимально необходимый процесс создания документации пользователя всех видов для программного средства, имеющего интерфейс пользователя. Данные виды охватывают печатную документацию (например, руководства пользователя и краткие справочные карты), диалоговую (оперативную) документацию, справочный текст («хелпы») и системы диалоговой документации.

Итак, исходя из всего выше написанного, видно, что основных документов в 34 ГОСТе 3: ГОСТ 34.201-89, РД 50-34.698-90 и ГОСТ 34.602-89.
При разработке пакета документации, для начала, необходимо открыть ГОСТ 34.201-89 и выбрать стадию создания Эскизный проект, Технический проект и Рабочая документация. Далее, следует выбрать документы для разработки, которые соответствуют стадии создания.

Перечень документов 34 ГОСТа

Стадия
создания
Наименование документа Код Часть
проекта
Принад
лежнос
ть к
проект
но-смет
ной доку
мента
ции
Принад
лежнос
ть к
эксплуа
тацион
ной до
кумен
тации
Дополнительные указания
ЭП Ведомость эскизного проекта ЭП* ОР
Пояснительная записка
К эскизному проекту
П1 ОР
ЭП, ТП Схема организационной структуры СО ОР Допускается включать в документ П3 или ПВ
Схема структурная комплекса
технических средств
С1* ТО Х Допускается включать в документ П9
Схема функциональной структуры С2* ОР При разработке документов СО, С1, С2, С3 на стадии ЭП допускается их включать в документ П1
Перечень заданий на разработку
специализированных (новых)
технических средств
В9 ТО Х При разработке на стадии ТП
допускается включать
в документ П2
Схема автоматизации С3* ТО Х
Технические задания на разработку
специализированных (новых)
технических средств
ТО В состав проекта не входят
ТП Задания на разработку
строительных, электротехнических,
санитарно-технических и
других разделов
проекта, связанных
с созданием системы
ТО Х В состав проекта не входят
Ведомость технического проекта ТП* ОР
Ведомость покупных изделий ВП* ОР
Перечень входных сигналов
и данных
В1 ИО
Перечень выходных сигналов
(документов)
В2 ИО
Перечень заданий на разработку
строительных, электротехнических,
санитарно-технических и
других разделов
проекта, связанных
с созданием системы
В3 ТО Х Допускается включать в документ П2
Пояснительная записка
к техническому проекту
П2 ОР Включает план мероприятий
по подготовке объекта к вводу
системы в эксплуатацию
Описание автоматизируемых
функций
П3 ОР
Описание постановки задач
(комплекса задач)
П4 ОР Допускается включать
в документы П2 или П3
Описание информационного
обеспечения системы
П5 ИО
Описание организации
информационной базы
П6 ИО
ТП Описание систем классификации и
кодирования
П7 ИО
Описание массива
информации
П8 ИО
Описание комплекса
технических средств
П9 ТО Для задачи допускается включать в документ 46 по ГОСТ 19.101
Описание программного
обеспечения
ПА ПО
Описание алгоритма
(проектной процедуры)
ПБ МО Допускается включать в документы П2, П3 или П4
Описание организационной
структуры
ПВ ОО
План расположения С8 ТО Х Допускается включать в документ П9
Ведомость оборудования
и материалов
ТО Х
Локальный сметный расчёт Б2 ОР Х
ТП, РД Проектная оценка
надёжности системы
Б1 ОР
Чертёж формы документа
(видеокадра)
С9 ИО Х На стадии ТП допускается
включать в документы
П4 или П5
РД Ведомость держателей
подлинников
ДП* ОР
Ведомость эксплуатационных
документов
ЭД* ОР Х
Спецификация оборудования В4 ТО Х
Ведомость потребности
в материалах
В5 ТО Х
Ведомость машинных носителей
информации
ВМ* ИО Х
Массив входных данных В6 ИО Х
РД Каталог базы данных В7 ИО Х
Состав выходных данных
(сообщений)
В8 ИО Х
Локальная смета Б3 ОР Х
Методика (технология)
автоматизированного
проектирования
И1 ОО Х
Технологическая инструкция И2 ОО Х
Руководство пользователя И3 ОО Х
Инструкция по формированию и
ведению базы данных
(набора данных)
И4 ИО Х
Инструкция по эксплуатации КТС ИЭ ТО Х
Схема соединений внешних проводок С4* ТО Х Допускается выполнять в
виде таблиц
Схема подключения
внешних проводок
С5* ТО Х То же
Таблица соединений и подключений С6 ТО Х
Схема деления системы
(структурная)
Е1* ТО
Чертёж общего вида ВО* ТО Х
Чертёж установки технических средств СА ТО Х
Схема принципиальная СБ ТО Х
Схема структурная комплекса
технических средств
С1* ТО Х
План расположения оборудования и проводок С7 ТО Х
Описание технологического
процесса обработки
данных (включая
телеобработку)
ПГ ОО Х
Общее описание системы ПД ОР Х
Программа и методика испытаний (компонентов, комплексов средств автоматизации, подсистемы,
систем)
ПМ* ОР
Формуляр ФО* ОР Х
Паспорт ПС* ОР Х
*Документы, код которых установлен в соответствии с требованиями стандартов ЕСКД

Примечание к таблице:

  1. В таблице приняты следующие обозначения:
    • ЭП — эскизный проект;
    • ТП — технический проект;
    • РД — рабочая документация;
    • ОР — общесистемные решения;
    • ОО — решения по организационному обеспечению;
    • ТО — решения по техническому обеспечению;
    • ИО — решения по информационному обеспечению;
    • ПО — решения по программному обеспечению;
    • МО — решения по математическому обеспечению.
  2. Знак Х — обозначает принадлежность к проектно-сметной или эксплуатационной документации.
  3. Номенклатуру документов одного наименования устанавливают в зависимости от принятых при создании системы проектных решений.

Когда перечень документов определён, то в РД 50-34.698-90 следует найти выбранные документы и разработать их строго по указанным пунктам. Все пункты содержания, которые указаны, обязательно должны быть в документе.
Если разрабатывается Техническое задание, то сразу нужно открыть ГОСТ 34.602-89 и разработать ТЗ строго согласно пунктам.

ГОСТ 19

Серия ГОСТов 19 (ГОСТ 19.ххх Единая система программной документации (ЕСПД)) состоит:

    1. ГОСТ 19.001-77 Общие положения — слишком общий документ, практической пользы он не несёт. Поэтому его можно пропустить.
    2. ГОСТ 19781-90 Термины и определения — хороший список определений в области программного обеспечения систем обработки информации. Кроме как определений больше не содержит ничего.
    3. ГОСТ 19.101-77 Виды программ и программных документов — один из главных документов 19 ГОСТа. Именно с него следует начинать работу с 19 ГОСТом, так как в нём содержится полный перечень и обозначения документов ГОСТа.

Перечень документов 19 ГОСТа

Код Вид документа Стадии разработки
Эскизный
проект
Технический
проект
Рабочий проект
компонент комплекс
Спецификация
05 Ведомость держателей подлинников
12 Текст программы
13 Описание программы
20 Ведомость эксплуатационных документов
30 Формуляр
31 Описание применения
32 Руководство системного программиста
33 Руководство программиста
34 Руководство оператора
35 Описание языка
46 Руководство по техническому
обслуживанию
51 Программа и методика испытаний
81 Пояснительная записка
90-99 Прочие документы

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

  1. ГОСТ 19.102-77 Стадии разработки — содержит описание стадий разработки. Полезен в образовательных целях. На мой взгляд, особой практической пользы не несёт.
  2. ГОСТ 19.103-77 Обозначения программ и программных документов — содержит описание присвоения номера (кода) документу. Даже после прочтения этого ГОСТа остаётся куча вопросов о том, как же присвоить этот самый номер документу.
  3. ГОСТ 19.104-78 Основные надписи — устанавливает формы, размеры, расположение и порядок заполнения основных надписей листа утверждения и титульного листа в программных документах, предусмотренных стандартами ЕСПД, независимо от способов их выполнения. Так как документы 19 ГОСТа оформляются в рамочках, то данный документ очень важен.
  4. ГОСТ 19.105-78 Общие требования к программным документам — устанавливает общие требования к оформлению программных документов. Требования слишком общие. Как правило для разработки документа этот ГОСТ почти не применяется, так как хватает специального ГОСТа на документ, но для общих знаний в данный ГОСТ все же лучше заглянуть разок.
  5. ГОСТ 19.106-78 Требования к программным документам, выполненным печатным способом — содержит требования к оформлению всех документов 19 ГОСТа.
  6. ГОСТ 19.201-78 Техническое задание, требования к содержанию и оформлению — устанавливает порядок построения и оформления технического задания на разработку программы или программного изделия.
    Пункты ТЗ 34 ГОСТа и 19 ГОСТа отличаются.
  7. ГОСТ 19.601-78 Общие правила дублирования, учёта и хранения — общие правила дублирования, обращения, учёта и хранения программных документов. В ГОСТе в нескольких пунктах описано как сделать так, чтобы документы не потерялись.
  8. ГОСТ 19.602-78 Правила дублирования, учёта и хранения программных документов, выполн-х печ. Способом — дополнение к ГОСТу 19.601-78.
  9. ГОСТ 19.603-78 Общие правила внесения изменений — устанавливает общие правила внесения изменений в программные документы. По сути, описывает длинный бюрократический алгоритм внесения изменений в документы.
  10. ГОСТ 19.604-78 Правила внесения изменений в программные документы, выполненных печатным способом — описывает порядок работы и заполнения с Листа регистрации изменений.

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

  1. ГОСТ 19.202-78 Спецификация. Требования к содержанию и оформлению;
  2. ГОСТ 19.301-79 Программа и методика испытаний. Требования к содержанию и оформлению;
  3. ГОСТ 19.401-78 Текст программы. Требования к содержанию и оформлению;
  4. ГОСТ 19.402-78 Описание программы;
  5. ГОСТ 19.403-79 Ведомость держателей подлинников;
  6. ГОСТ 19.404-79 Пояснительная записка. Требования к содержанию и оформлению;
  7. ГОСТ 19.501-78 Формуляр. Требования к содержанию и оформлению;
  8. ГОСТ 19.502-78 Описание применения. Требования к содержанию и оформлению;
  9. ГОСТ 19.503-79 Руководство системного программиста. Требования к содержанию и оформлению;
  10. ГОСТ 19.504-79 Руководство программиста. Требования к содержанию и оформлению;
  11. ГОСТ 19.505-79 Руководство оператора. Требования к содержанию и оформлению;
  12. ГОСТ 19.506-79 Описание языка. Требования к содержанию и оформлению;
  13. ГОСТ 19.507-79 Ведомость эксплуатационных документов;
  14. ГОСТ 19.508-79 Руководство по техническому обслуживанию. Требования к содержанию и оформлению.

Порядок работы с 19 ГОСТом:

  1. В ГОСТе 19.101-77 выбрать документ и его код согласно стадии разработки.
  2. Согласно ГОСТу 19.103-77 присвоить номер документу.
  3. Затем по ГОСТам 19.104-78 и 19.106-78 оформить документ.
  4. Из специализированного списка ГОСТов следует выбрать тот, который соответствует разрабатываемому документу.

Заключение

ГОСТ — это не страшно и несложно! Главное понять, что нужно написать и какой для этого ГОСТ используется. Наши основные ГОСТы 19 и 34 для написания документации очень старые, но и по сей день актуальны. Написание документации по стандарту снимает множество вопросов между исполнителем и заказчиком. Следовательно, несёт в себе экономию времени и денег.

DocPlace 2017-12-11

1 комментарий к записи «Создание документации для информационных систем по ГОСТ 34 и ГОСТ 19»

  1. Извините за то, что вмешиваюсь… Мне знакома эта ситуация. Приглашаю к обсуждению. Пишите здесь или в PM.

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *