СТ РК 1087-2002 ЕСПД. Руководство пользователя. Требования к составу, содержанию и оформлению

ГОСУДАРСТВЕННЫЙ СТАНДАРТ РЕСПУБЛИКИ КАЗАХСТАН

 

ЕДИНАЯ СИСТЕМА ПРОГРАММНОЙ ДОКУМЕНТАЦИИ

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

ТРЕБОВАНИЯ К СОСТАВУ, СОДЕРЖАНИЮ И ОФОРМЛЕНИЮ

 

СТ РК 1087-2002

 

Издание официальное

 

Комитет по стандартизации, метрологии и сертификации

Министерства индустрии и торговли Республики Казахстан

 

(Госстандарт)

 

Астана

 

ПРЕДИСЛОВИЕ

1 РАЗРАБОТАН И ВНЕСЕН ТОО «АИСТ» Техническим комитетом № 41 по стандартизации ''Автоматизация и информатизация

2 УТВЕРЖДЕН И ВВЕДЕН В ДЕЙСТВИЕ приказом Комитета по стандартизации, метрологии и сертификации Министерства индустрии и торговли Республики Казахстан от 19 декабря 2002 г № 473

3 СРОК ПЕРВОЙ ПРОВЕРКИ                                                                   2007 год

ПЕРИОДИЧНОСТЬ ПРОВЕРКИ                                                             5 лет

4 ВВЕДЕН ВПЕРВЫЕ

 

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

 

1      Область применения

2      Нормативные ссылки

3      Определения

4      Требования к документам, входящих в руководство пользователя

 

ГОСУДАРСТВЕННЫЙ СТАНДАРТ РЕСПУБЛИКИ КАЗАХСТАН

 

Дата введения 2004.01.01

 

1 Область применения

 

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

Настоящий стандарт устанавливает и определяет минимальные требования к структуре и содержанию руководства пользователя.

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

 

2 Нормативные ссылки

 

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

СТ РК 1091-2002 Единая система программной документации. Термины и определения.

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

 

3 Определения

 

В настоящем стандарте применяются термины и определения в соответствии с СТ РК 1091-2002

 

4 Требования к документам, входящих в руководство пользователя

 

4.1 Определение требуемых документов пользователя

 

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

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

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

Категории пользователей программным обеспечением подразделяется на следующие группы:

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

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

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

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

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

4.1.3 Определение набора документов. Набор документов может состоять из одного или нескольких документов в зависимости от объема представляемой информации и потребностей выбранной аудитории.

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

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

4.1.4 Определение способа использования документов. Если документация требуется пользователю для изучения программного обеспечения, то документация используется в виде инструкции.

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

Документы, используемые в виде инструкции, могут быть информационно-ориентированными или ориентированными на задачу (см. н.4.1.4.1).

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

4.1.4.1 Использование в виде инструкции. Документ, используемый в виде инструкции должен приводить:

- базовые понятия и информацию, необходимые для понимания программного обеспечения;

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

- примеры, облегчающие процесс изучения.

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

- обзор;

- теоретические сведения, используемые в руководстве по использованию;

- учебник.

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

Документы, ориентированные на задачу и используемые в виде инструкции, должны включать:

- руководство по диагностике при выполнении процедур;

- руководство по эксплуатации;

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

- организовать и представить необходимую информацию;

- обеспечить свободный метод поиска информации. Документы, используемые как справочники, должны включать:

- руководство по командам;

- руководство по сообщениям об ошибках;

- руководство по вызову программ;

- руководство по быстрому поиску информации;

- руководство по инструментальным программным средствам;

- руководство по служебным программам.

 

 

4.2 Требования к составу документов для пользователя

 

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

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

Таблица 1 определяет 12 базовых компонентов документа для пользователя программного обеспечения. При необходимости может быть добавлена дополнительная информация.

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

 

Таблица 1- Компоненты документа пользователя программного обеспечения

 

 

Таблица 2 - Требования к составу

 

 

Примечание - В таблице применены следующие обозначения:

О - Обязательный структурный элемент.

Н - Необязательный структурный элемент.

С — Разрешается вместо структурного элемента вставить ссылку.

* - Должна быть указана взаимосвязь с другими томами.

1 - Документ имеет содержание. Требование к содержанию документа приводятся в пунктах 4.3.7.1 и 4.3.7.2.

2 - Индекс необходим для документа из 40 и более страниц, в остальных случаях не обязателен.

 

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

 

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

Для удобства изложения, настоящий стандарт использует общепринятые заголовки или названия при определении частей документа для пользователя. Как отмечено в пункте 4.2, в документе пользователя использование именно этих названий необязательно. Например, во введении описании аудитории и области применения не обязательно должны быть озаглавлены "Описание аудитории" и "Область применения".

4.3.1 Титульный лист. Титульный лист документа для пользователя должен включать следующую информацию:

- название документа;

- версию документа и дату;

- рассматриваемое программное обеспечение;

- наименование выпускающей организации. Дизайн и расположение этих элементов на странице определяется ГОСТ 19.104.

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

4.3.3 Гарантии и контрактные обязательства. Должны быть определены любые гарантии, контрактные обязательства или ограничения прав.

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

- полное оглавление всего документа;

- сокращенное оглавление, при этом перед каждым разделом приводится полное оглавление раздела.

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

- полное оглавление тома;

- сокращенное оглавление тома, при этом приводится полное оглавление раздела перед каждым разделом.

4.3.4.1 Полное оглавление. Полное оглавление всего документа или отдельного раздела должно строиться следующим образом:

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

- определяются ссылки на страницы для каждой единицы;

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

1) строка-лидер (строка точек в форме "...") или аналогичное средство, связывающее название и номер страницы;

2) пропуск двойного интервала между названиями.

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

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

- номер и название иллюстрации;

- номер страницы, где расположена иллюстрация;

- использовать способ, помогающий пользователю связать название иллюстрации с соответствующей страницей, например:

1) строку лидер (строка точек в форме "...") или аналогичное средство, связывающее название и номер страницы;

2) пропуск двойного интервала между названиями.

4.3.6 Введение. Во введение необходимо включать следующую информацию:

- описание категории пользователей;

- область применения;

- назначение;

- описание использования документа;

- список дополнительных документов и дополнительной информации;

- описание соглашений;

- инструкции по обратной связи.

4.3.6.1 Описание категории пользователей. В этом структурном элементе должно приводиться описание контингента, для которого предназначен документ.

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

Для категории пользователя определяется:

- предполагаемый уровень практической подготовки пользователя;

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

4.3.6.2 Область применения. В этом структурном элементе необходимо указать версию программного обеспечения, соответствующую документу, номер версии документа, окружение (аппаратное и программное), в котором должно функционировать программное обеспечение.

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

4.3.6.4 Описание использования документа. В этом структурном элементе надо описать содержание каждого раздела документа, его назначение и связи с другими разделами.

4.3.6.5 Список дополнительных документов и дополнительной информации. В этом структурном элементе надо привести список дополнительных документов и указать связь данного документа с приведенными.

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

4.3.6.6 Соглашения. В этом структурном элементе должны быть приведены обозначения, стилистические соглашения и соглашения по синтаксису, принятые в документе.

4.3.6.6.1 Обозначения. В этом структурном элементе необходимо описать и изобразить все специальные обозначения, используемые в документе.

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

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

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

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

4.3.7 Содержание, организация и способ изложения документа определяются после определения режима его использования: в виде инструкции или в виде справочника.

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

Следует использовать изложение по темам, например:

- теория;

- возможности программного обеспечения;

- архитектура программного обеспечения.

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

Связи между задачами используются для организации документа, ориентированного на задачу, или его раздела; например, возможна организация:

- по группам задач;

- по последовательностям задач.

4.3.7.1.1 Предметная область. Раздел следует начинать с описания предметной области, к которой принадлежит обсуждаемый материал.

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

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

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

4.3.7.1.4 Предостережения и предупреждения. Описываются общие предостережения и предупреждения, относящиеся к задаче.

Конкретные предостережения и предупреждения размещаются на той же странице и непосредственно перед теми действиями, которые требуют предостережений и предупреждений. (См. раздел 3 для определения терминов "предостережение" и "предупреждение").

4.3.7.1.5 Метод. Описывается каждая задача, включая описание:

- действий пользователя;

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

- возможных ошибок, способов избежать их или исправить;

- ожидаемых результатов.

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

4.3.7.2 Содержание документа, используемого в виде справочника.

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

- по командам;

- из меню;

- системными вызовами.

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

4.3.7.2.1 Назначение. В этом структурном элементе должны быть описаны назначения функций.

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

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

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

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

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

4.3.7.2.5 Предостережения и предупреждения. В этом структурном элементе должны быть описаны общие предостережения и предупреждения, относящиеся к каждой функции. Конкретные предостережения и предупреждения размещаются на той же странице и непосредственно перед теми действиями, которые требуют предостережений и предупреждений.

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

- требуемые параметры;

- необязательные параметры;

- опции, задаваемые по умолчанию;

- порядок и синтаксис.

4.3.7.2.7 Прекращение выполнение. В этом структурном элементе должны быть описаны способы прерывания выполнения функции и возобновления выполнения.

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

4.3.7.2.9 Вывод. В этом структурном элементе должны быть описаны результаты выполнения функции, такие как:

- вывод на экран дисплея;

- влияние на файлы или данные;

- значения кода завершения или выходные параметры;

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

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

- ограничения;

- замечания;

- дополнительные функции.

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

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

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

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

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

- коды, используемые во входных или выходных данных (например, коды стран или товаров);

- взаимодействие между задачами или функциями;

- глобальные ограничения обработки;

- описание форматов данных или структур файлов;

- примеры файлов, сообщений, программ.

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

4.3.11 Словарь. Необходимо в алфавитном порядке привести список определений:

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

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

Описание сокращений и аббревиатур могут быть расположены в отдельных разделах.

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

- определяется важность информации; менее важные ключевые слова располагаются за более важными;

- справа от элемента индекса указываются ссылки на места в тексте, где этот элемент использован;

- ссылки располагаются одним из следующих способов:

1) по страницам;

2) по номерам разделов или параграфов;

3) по номерам иллюстраций;

4) по другим элементам индекса.

- используется только один уровень ссылок внутри индекса. Например, если один элемент индекса ссылается на второй элемент индекса, то второй элемент должен ссылаться на номер страницы, номер раздела или параграфа, номер иллюстрации. Второй элемент индекса не должен ссылаться на третий элемент индекса.

 

4.4 Требования к форме представления документа пользователи

 

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

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

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

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

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

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

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