Руководство пользователя ieee - Большая энциклопедия инструкций и руководств

Current projects that have been authorized by the IEEE SA Standards Board to develop a standard.

No Active Projects

Standards approved by the IEEE SA Standards Board that are within the 10-year lifecycle.

No Active Standards

These standards have been replaced with a revised version of the standard, or by a compilation of the original active standard and all its existing amendments, corrigenda, and errata.

1063-1987

IEEE Standard for Software User Documentation

Minimum requirements for the structure and information content of user documentation are provided. They apply primarily to technical substance rather than to style. Editorial and stylistic considerations are addressed only when they impact structure and content. Only traditional documentation, either printed on paper or stored in some other medium in the format of a printed document and used in a manner analogous to the way a printed document is used, is addressed.

Learn More About 1063-1987

These standards have been removed from active status through a ballot where the standard is made inactive as a consensus decision of a balloting group.

No Inactive-Withdrawn Standards

These standards are removed from active status through an administrative process for standards that have not undergone a revision process within 10 years.

No Inactive-Reserved Standards

Источник

Сравнительный анализ структур руководств пользователя программы по ЕСПД и IEEE Std 1063-2001 с учетом рекомендаций «манифеста Кагарлицкого». Показано, что обобщенная структура руководства пользователя, собранная согласно требованиям «устаревших» ГОСТов 19-й системы, существенно превосходит структуру руководства, рекомендуемую суперсовременным IEEE Std 1063-2001. Редакция от 23.01.2022.

Создан 11.02.2005 11:14:22

Когда умирает надежда, приходит отчаяние.

Мудрая латинская поговорка

Как писать руководство пользователя программы? Создать древовидную иерархическую структуру разделов руководства пользователя и заполнить ее разделы содержимым. И вся любовь.

Где взять структуру разделов руководства пользователя? С руководствами на изделия (руководство по эксплуатации по ГОСТ 2.601-95) и на автоматизированные системы (руководство пользователя по РД 50-34.698-90) все более или менее ясно. А вот сам документ «Руководство пользователя» программы в ГОСТах 19-й системы отсутствует как класс.

Каким содержимым наполнять разделы руководства пользователя? Как быть? Главное — не отчаиваться.

Цели и задачи статьи

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

Задачи:

проанализировать существующие стандарты и рекомендации по разработке эксплуатационной программной документации, выявить достоинства и недостатки каждого документа по отдельности;
вывести некую обобщенную структуру руководства пользователя по ГОСТам 19-й системы из имеющегося набора эксплуатационных программных документов;
сравнить ее со структурой, рекомендованной IEEE Std 1063-2001;
а все прочие задачи перекочевали во 2-ю часть статьи…

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

Вопросы, на которые должно дать ответы руководство пользователя

Подарите ребенку незнакомую ему электронную игрушку. Перечень вопросов будет примерно таким (если сразу же не разломает):

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

Последовательность вопросов может оказаться самой разнообразной. И документ под названием «Руководство пользователя» должен дать ответы на все поставленные вопросы. Все просто. Не так страшен черт, как его малюют.

Руководство пользователя: четыре источника и четыре составных части

Располагаем документами:

«метагайдом» Кагарлицкого;
суперсовременным IEEE Std 1063-2001, «IEEE Standard for Software User Documentation»;
классическими отечественными ГОСТами 19-й системы, включающим в себя перечисленные ниже документы «описательного» характера:
- ГОСТ 19.402-78 ЕСПД. Описание программы;
- ГОСТ 19.502-78 ЕСПД. Описание применения. Требования к содержанию и оформлению;
- ГОСТ 19.503-79 ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению;
- ГОСТ 19.504-79 ЕСПД. Руководство программиста. Требования к содержанию и оформлению;
- ГОСТ 19.505-79 ЕСПД. Руководство оператора. Требования к содержанию и оформлению.

Крайняя четверка из перечня — эксплуатационные программные документы.

Возможно, существуют и иные документы, но автору, основательно порывшемуся в рунетовской свалке, ничего более подходящего заполучить пока не удалось. Яндекс обнаружил в своих недрах еще одну страничку с названием «Как сделать хорошее руководство пользователя», автор которой именует себя на американЬский манер (типа John P. Morgan). Двухстраничное «наставление» с радостными возгласами было немедленно отправлено в корзину.

Манифест Кагарлицкого

Метагайд Кагарлицкого показался многообещающим. Только автор настоящей статьи не уразумел, что есть «метагайд», поэтому позволил себе наглось обозвать метагайд «манифестом». И не погрешил против истины (но это открылось позже — ниже).

(цитаты из манифеста Кагарлицкого)

Мы стремились свести в единую систему всю совокупность типовых требований, которые должны, с нашей точки зрения, предъявляться к технической документации: руководствам, справочникам и т.д. При этом мы основывались на стандартах(!!!) ГОСТ, стандартах компании Microsoft, опыте наших сотрудников и других разработчиков технической документации.

Начало обнадеживающее.

В состав технической документации входят две стержневые части, которые мы будем называть соответственно руководством пользователя и справочником пользователя, или коротко: руководством и справочником (по аналогии с английскими словосочетаниями User’s Guide и User’s Reference). Они могут быть оформлены в виде отдельных документов (для крупных программных продуктов), а могут, напротив, существовать в интегрированном виде. Между ними даже может не быть четкой границы: единый текст способен совмещать в себе черты руководства и черты справочника.

Что-то не так. Автору статьи всегда «казалось», что термин техническая документация трактуется более широко, значительно шире, чем эксплуатационная (программная) документация.

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

По-понятиям так по-понятиям, вот только пацаны начинают нервничать. Руководство не есть понятие, а есть вид документа.

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

На небосклоне засияла звезда по имени Надежда — сейчас уважаемый г-н Кагарлицкий выдаст нам, лишенцам, всеобъемлющую иерархическую структуру руководства пользователя всех времен и народов. Ну же?!

Прежде чем приступить к разработке документации как таковой, необходимо наметить и спланировать общую логику изложения. Может показаться, что жанр технической документации крайне прост: ведь его задачей является «всего лишь» сообщение пользователю некоторых сведений о продукте. Однако если Вы будете исходить из этого в своей работе, Вы будете создавать образцы документации, вовсе непригодные или едва пригодные для практического использования, — даже если все необходимые сведения будут там содержаться. Ваша задача состоит в том, чтобы провести пользователя через перевал, то есть найти в горной цепи место, которое хотя бы и с трудом, но все-таки проходимо для Вашего «подопечного».

Жаль… А так все хорошо начиналось. Со «стандартов ГОСТ» — «стандартов ГОсударственных СТандартов» — простим г-на Кагарлицкого за тавтологию. Только вот решения первой задачи, поставленной автором настоящей статьи, в семидесятидвухстраничном манифесте (Arial’ом 12pt) нет. Уважаемый автор манифеста лишь поставил нам задачу. Что ж, нет пророка в своем отечестве. Может, есть пророк в отечестве буржуйском?

Руководство пользователя по IEEE Std 1063-2001 «IEEE Standard for Software User Documentation»

Забугорный «пророческий» документ IEEE Std 1063-2001 (IEEE в простонародье — «ай-яй-яй») в подразделе 1.2 (Puprose) содержит такую строчку:

This revision provides requirements for the structure, information content, and format of both printed and electronic documentation.

В авторском понимании назначение (намерение, цель, замысел, стремление) документа IEEE Std 1063-2001 состоит в «обеспечении требований к структуре, информационному наполнению, форматированию (оформлению) как электронной, так и печатной пользовательской документации по программным средствам». Что ж, подходяще. Какую же структуру руководства пользователя предлагает IEEE Std 1063-2001?

Структура руководства пользователя по IEEE Std 1063-2001

Опциональная типовая структура руководства пользователя содержится в таблице из раздела Structure of software user documentation документа IEEE Std 1063-2001:

Component	See subclause	Required?
Identification data (package label/title page)	4.3	Yes
Table of contents	5.7.1	Yes, in documents of more than eight pages after identification data
List of illustrations	5.7.2	Optional
Introduction	3.2	Yes
Information for use of the documentation	4.4	Yes
Concept of operations	4.5	Yes
Procedures	4.6, 4.7	Yes (instructional mode)
Information on software commands	4.8	Yes (reference mode)
Error messages and problem resolution	4.9	Yes
Glossary	4.10	Yes, if documentation contains unfamiliar terms
Related information sources	4.11	Optional
Navigational features	5.8	Yes
Index	5.7.3	Yes, if documents of more than 40 pages
Search capability	5.7.4	Yes, in electronic documents

For purposes of this standard, the following non-mandatory nomenclature is used for the structural parts of software user documentation. A printed document is structured into logical units called chapters, subdivided into topics, which may be subdivided into subtopics, and printed on physical units called pages.

Здорово. IEEE Std 1063-2001 предлагает «все взять и поделить» — разбить разделы руководства на главы, топики, субтопики и т.д. И наступит всем счастье.

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

Introduction

Какие сведения должны быть изложены в разделе Introduction согласно IEEE Std 1063-2001? А вот какие

The introduction shall describe the intended audience, scope, and purpose for the document and include a brief overview of the software purpose, functions, and operating environment.

Что ж, замечательно. Структура подразделов Introduction начинает как-то вырисовываться.

Information for use of the documentation

The documentation shall include information on how it is to be used (for example, help on help), and an explanation of the notation (a description of formats and conventions-see 5.8). At least one document in a document set shall identify all documents in the set by title and intended use, including recommendations on which members of the audience should consult which sections of the documentation. In document sets comprising many volumes or products, this information may be provided in a separate «road map» or guide to the document set. Documentation may include identification and discussion of notable changes from the previous version of the document set and the software.

Весьма полезный раздел (в контексте разработки руководства пользователя). Руководство по руководству.

Concept of operations

Documentation shall explain the conceptual background for use of the software, using such methods as a visual or verbal overview of the process or workflow; or the theory, rationale, algorithms, or general concept of operation. Explanations of the concept of operation should be adapted to the expected familiarity of the users with any specialized terminology for user tasks and software functions. Documentation shall relate each documented function to the overall process or tasks. Conceptual information may be presented in one section or immediately preceding each applicable procedure.

Концептуальная информация безусловно важна.

Procedures

Task-oriented instructional mode documentation shall include instructions for routine activities that are applied to several functions:

— Software installation and de-installation, if performed by the user

— Orientation to use of the features of the graphical user interface (see 5.6)

— Access, or log-on and sign-off the software

— Navigation through the software to access and to exit from functions

— Data operations (enter, save, read, print, update, and delete)

— Methods of canceling, interrupting, and restarting operations

These common procedures should be presented once to avoid redundancy when they are used in more complex functions.

И пошла конктерика. Молодцы, буржуи!

Information on software commands

Documentation shall explain the formats and procedures for user-entered software commands, including required parameters, optional parameters, default options, order of commands, and syntax. Documentation may be provided on the development and maintenance of macros and scripts. Reference mode documentation shall contain a reference listing of all reserved words or commands. Examples should illustrate the use of commands. Documentation shall explain how to interrupt and undo operation during execution of a command and how to restart it, if possible. Documentation shall describe how to recognize that the command has successfully executed or abnormally terminated.

Error messages and problem resolution

Documentation should address all known problems in using the software in sufficient detail such that the users can either recover from the problems themselves or clearly report the problem to technical support personnel. Reference mode documentation shall include each error message with an identification of the problem, probable cause, and corrective actions that the user should take. A quick reference card may address error messages by referring the user to more detailed reference documentation. The documentation on resolving problems shall also include contact information for reporting problems with software or its documentation and suggesting improvements.

Выводы по IEEE Std 1063-2001

Но счастье оказалось неполным… Структура разделов первого уровня руководства показана в таблице явно. А дальше — «милый мой, хороший, догадайся сам» («догадайся, мол, сама»). IEEE Std 1063-2001, конечно, «provides requirements for the structure», но не предлагает явной структуры руководства пользователя до рекомендованного ГОСТ 2.105 четвертого уровня вложенности.

Рекомендации типа «Documentation shall explain…», «Examples should illustrate…», «Documentation shall describe…» и им подобные, безусловно, проверены временем. В руководстве пользователя надо и объяснять, и иллюстрировать, и описывать — без всякого сомнения. Но все это и козе понятно, и в ГОСТах 19-й системы прописано.

Итак, вряд ли целесообразно разрабатывать руководства пользователя, основываясь исключительно на рекомендациях IEEE Std 1063-2001. Причины, как минимум, две:

отсутствие в IEEE Std 1063-2001 четко регламентированной структуры руководства пользователя;
«поверхностность» IEEE Std 1063-2001, отсутствие «широты охвата» и «глубины проработки».

Отсутствие четко регламентированной структуры руководства пользователя даст возможность заказчику ТРЕТИРОВАТЬ разработчика, см. хотя бы Страшная правда о техническом задании. Бедняга-разработчик будет вынужден, по указке заказчика, изо дня в день менять местами разделы руководства пользователя (гарантированный минимум, полученный опытным путем).

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

По мнению автора, рекомендации IEEE Std 1063-2001, разработанного при участии сотни забугорных спецов, весьма и весьма поверхностны. Не сможет разработчик, работая по IEEE Std 1063-2001, охватить максимум «характеристик», свойственных программе. В IEEE Std 1063-2001 многие из них попросту не прописаны. Отсутствуют «широта охвата» и «глубина проработки», свойственные отечественным документам.

В крайнем разделе настоящей статьи приведена таблица соответствия ГОСТ 19 и IEEE Std 1063-2001, которую автор статьи начал было составлять, затем бросил и проверять не стал. А выводы пусть каждый сделает сам для себя. И, возможно, в чем-то поправит автора.

Пользовательские документы по ГОСТ 19 (ЕСПД)

В отличие от суперсовременного буржуйского IEEE Std 1063-2001, древние, многими ругаемые отечественные стандарты 19-й системы (Единая система программной документации — ЕСПД) содержат не пространные рассуждения о том, что и как должно разъяснять, иллюстрировать и описывать руководство пользователя, а конкретные требования к структуре и содержанию пользовательских (эксплуатационных) документов.

Перечень ГОСТов 19 «описательного» характера, на основе которых можно, не мудрствуя лукаво, сформировать четкую структуру разделов каждого из «описательных» документов, приведен в разделе Источники. Основной прием — детализация — подробно описан в статье «Как писать техническое задание?!». Далее — сформированные «детализацией» структуры разделов документов согласно ГОСТам из перечня.

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

Структура разделов описания применения по ГОСТ 19.502-78

Структура разделов руководства системного программиста по ГОСТ 19.503-79

Структура разделов руководства программиста по ГОСТ 19.504-79

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

Выводы по ГОСТам 19.ххх

Ни ГОСТ 19.505-79, ни ГОСТ 19.504-79, ни ГОСТ 19.503-79, взятые по одельности, не могут похвастаться достаточной полнотой структуры.

Зато структуры «описательных» документов ГОСТ 19 обладают как полностью идентичными (по тексту названий), так и схожими по тексту названий разделами и подразделами. К идентичным разделам относятся, к примеру, разделы «Аннотация», имеющие место во всех документах согласно ГОСТ 19.105-78. К схожим (фактически — идентичным) можно отнести подразделы «Назначение программы» и «Сведения о назначении программы».

А почему не попытаться объединить все «описательные» документы? Объединить идентичные и схожие разделы документов, выделить специфические разделы? Быть может, удастся избавиться от неполноты ГОСТ 19.505-79, ГОСТ 19.504-79 и ГОСТ 19.503-79 и получить обобщенную структуру «описательного» документа и обозвать сам документ руководством пользователя программы?

ГОСТы 19.ххх допускают «вводить дополнительные разделы или объединять отдельные разделы», а также «вводить новые». Согласно ГОСТ 19.101-77 «Допускается объединять отдельные виды эксплуатационных документов (за исключением ведомости эксплуатационных документов и формуляра). Необходимость объединения этих документов указывается в техническом задании. Объединенному документу присваивают наименование и обозначение одного из объединяемых документов. В объединенных документах должны быть приведены сведения, которые необходимо включать в каждый объединяемый документ [из 2.6 ГОСТ 19.101-77]»

Сказано — сделано. Только мы нарушим ГОСТы и создадим объединенный документ под названием «Руководство пользователя».

Обобщенная структура руководства пользователя по ГОСТам 19-й системы

Путем слияния структур «описательных» документов ГОСТов 19-й системы в единую структуру, удаления «лишних» одноименных разделов, слияния схожих разделов сформирована общая структура руководства пользователя программы. В табличке сведены и «*» отмечены разделы, присутствующие в каждом отдельном документе.

ГОСТ 19.ххх — обобщенная структура разделов руководства	ГОСТ 19.402-78	ГОСТ 19.502-78	ГОСТ 19.503-79	ГОСТ 19.504-79	ГОСТ 19.505-79
Аннотация	*	*	*	*	*
•Назначение документа	*	*	*	*	*
•Краткое изложение основной части документа	*	*	*	*	*
Общие сведения о программе	*		*
•Обозначение и наименование программы	*			*
•Языки программирования, на которых написана программа	*
•Сведения о назначении программы	*	*	*	*	*
••Информация, достаточная для понимания функций программы и ее эксплуатации					*
•••Возможности программы		*
•••Классы решаемых задач	*
••••Описание задач		*
••••Методы решения задач		*
•••Функции, выполняемые программой			*	*
••Описание основных характеристик и особенностей программы		*		*
•••Временные характеристики				*
•••Режим работы				*
•••Средства контроля правильности выполнения и самовосстанавливаемости программы				*
••Ограничения области применения программы		*
•••Сведения о функциональных ограничениях на применение	*
Условия применения программы		*		*	*
•Условия, необходимые для выполнения программы		*	*		*
••Сведения о технических и программных средствах, обеспечивающих выполнение программы			*
•••Требования к техническим средствам	*	*
••••Типы ЭВМ, устройства, используемые при работе программы	*
••••Объем оперативной памяти				*
••••Минимальный и (или) максимальный состав аппаратурных и программных средств					*
••••Требования к составу и параметрам периферийных устройств				*
•••Программное обеспечение, необходимое для функционирование программы	*
••••Требования к программному обеспечению				*
••••Требования к другим программам		*
••••Требования и условия организационного, технического и технологического характера		*
Описание логической структуры	*
•Алгоритм программы	*
•Используемые методы	*
•Сведения о структуре программы	*		*
•Сведения о составных частях программы			*
•Описание функций составных частей	*
•Сведения о связях между составными частями программы	*		*
•Сведения о связях с другими программами	*		*
Сведения о входных и выходных данных		*		*
•Общие характеристики входной и выходной информации		*
•Сведения о входных данных	*	*
••Характер, организация и предварительная подготовка входных данных	*			*
•Сведения о выходных данных	*	*
••Характер и организация выходных данных	*			*
••Формат, описание и способ кодирования выходных данных	*
•Описание кодирования информации				*
Настройка программы			*
•Описание действий по настройке программы			*
••Настройка на состав технических средств			*
••Выбор функций			*
••Поясняющие примеры			*
Проверка программы			*
•Описание способов проверки работоспособности программы			*
••Контрольные примеры			*
••Методы прогона			*
••Результаты			*
Выполнение программы					*
•Загрузка программы •Способ вызова программы с соответствующего носителя данных •Описание процедур вызова программы	*			*	*
•Запуск программы					*
•Входные точки в программу*	*
•Способы передачи управления и параметров данных				*
•Выполнение программы					*
••Описание выполняемой функции 1					*
••Формат и возможные варианты команд для выполнения функции 1					*
••Ответы программы на команды выполнения функции 1					*
•Завершение выполнения программы					*
Дополнительные возможности			*
•Описание дополнительных функциональных возможностей программы			*
•Описание применения дополнительных функциональных возможностей программы			*
Сообщения программы			*	*	*
•Тексты сообщений, выдаваемых в ходе (настройки, проверки, выполнения) программы			*	*	*
••Описание содержания			*	*	*
••Описание действий, которые необходимо предпринять по этим сообщениям			*	*	*

Выводы по обобщенной структуре руководства пользователя по ГОСТ 19.ххх

Обобщенная структура руководства пользователя по ГОСТ 19.ххх явно не страдает, как IEEE Std 1063-2001, отсутствием широты охвата. Избыток, как известно, рождает качество. Перечислено все, чем может характеризоваться программа. Отдельные подразделы могут показаться даже излишними, к примеру, подраздел «Языки программирования, на которых написана программа».

Казалось бы, какое дело пользователю, на каком языке был написан исходный текст программы? С другой стороны, может «…это кому-нибудь нужно? Значит — это необходимо…». Ведь хочется при покупке буржуйского телевизора заполучить и принципиальную схему на него. Самсунги и соньки тоже выходят из строя. А вдруг неисправность пустяковая и устранить ее представляется возможным в домашних условиях, без поездки в сервисный центр?

В то же время, при всей широте охвата, в явном виде отсутствуют:

Software installation and de-installation, if performed by the user;
Orientation to use of the features of the graphical user interface;
Access, or log-on and sign-off the software;
Navigation through the software to access and to exit from functions и многое другое.

Автору удалось разбросать кое-что в разделе Таблица соответствия ГОСТ 19.ххх и IEEE Std 1063-2001, но времени «наморщить ум» всегда не хватает, руководство пользователя, как всегда, должно было быть готово еще на прошлой неделе.

Показать связи разделов обобщенного руководства пользователя с разделами ГОСТ 19.201-78 ЕСПД. Техническое задание, требования к содержанию и оформлению автор поленился, поскольку указанные связи очевидны.

Выводы по источникам

Итак, если первые три задачи в целом решены, крайняя задача осталась нерешенной.

Автор манифеста более склонен к рекомендациям по подбору слов* и построению предложений, IEEE Std 1063-2001, в лучшем случае, приводит требования к структуре руководства пользователя, но не дает особой конкретики, в ГОСТ 19.ххх не прописаны процедуры заполнения содержимым разделов руководства. Может, организовать эдакую смесь французского с нижегородским? Использовать все четыре источника в качестве четырех составных частей?

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

Смесь французского с нижегородским

Почему бы нет? Взять лучшее из ГОСТов 19-й системы, — обобщенную структуру руководства пользователя, добавить к ней немногочисленные толковые рекомендации из IEEE Std 1063-2001 и разбавить неисчерпаемой стилистической культурой и ресурсами языка из манифеста Кагарлицкого? Придать смеси стройный строгий вид, сформировать очередной учебно-тренировочный документ с подробными комментариями? А что делать, если ни один из перечисленных выше источников и составных частей в отдельности не способны дать ответы на все поставленные вопросы?

Таблица соответствия ГОСТ 19 и IEEE Std 1063-2001

ГОСТ 19.ххх	IEEE Std 1063-2001
Аннотация	Introduction
	The introduction shall describe the intended audience, scope, and purpose for the document and include a brief overview of the software purpose, functions, and operating environment
•Назначение документа	purpose for the document (Introduction)
•Краткое изложение основной части документа	scope (Introduction)
Общие сведения о программе
•Обозначение и наименование программы	аналогичный подраздел отсутствует
•Языки программирования, на которых написана программа	то же
•Сведения о назначении программы	brief overview of the software purpose (Introduction)
••Информация, достаточная для понимания функций программы и ее эксплуатации	аналогичный подраздел отсутствует
•••Возможности программы	то же
•••Классы решаемых задач	»
••••Описание задач	»
••••Методы решения задач	Documentation shall relate each documented function to the overall process or tasks
•••Функции, выполняемые программой	brief overview of the software … functions (Introduction)
••Описание основных характеристик и особенностей программы	аналогичный подраздел отсутствует
•••Временные характеристики	то же
•••Режим работы	»
•••Средства контроля правильности выполнения и самовосстанавливаемости программы	»
••Ограничения области применения программы	»
•••Сведения о функциональных ограничениях на применение	»
Условия применения программы	If different versions of the software are available for different operating environments, the title page should specify the applicable operating environment(s), including version(s) of hardware, communications, and operating system(s) (4.3. Content of identification data)
•Условия, необходимые для выполнения программы	аналогичный подраздел отсутствует
••Сведения о технических и программных средствах, обеспечивающих выполнение программы	Documentation for the hardware and software environment (4.11 Information on related information sources)
•••Требования к техническим средствам	аналогичный подраздел отсутствует
••••Типы ЭВМ, устройств, используемые при работе программы	то же
••••Объем оперативной памяти	»
••••Минимальный и (или) максимальный состав аппаратурных и программных средств	»
••••Требования к составу и параметрам периферийных устройств	»
•••Программное обеспечение, необходимое для функционирование программы	brief overview of the … operating environment (Introduction)
••••Требования к программному обеспечению	аналогичный подраздел отсутствует
••••Требования к другим программам	то же
•••Требования и условия организационного, технического и технологического характера	»
Описание логической структуры
•Алгоритм программы	algorithms (4.5 Concept of operations)
•Используемые методы	using such methods as a visual or verbal overview of the process or workflow (4.5 Concept of operations)
•Сведения о структуре программы	аналогичный подраздел отсутствует
•Сведения о составных частях программы	то же
•Описание функций составных частей	»
•Сведения о связях между составными частями программы	»
•Сведения о связях с другими программами	»
Сведения о входных и выходных данных
•Общие характеристики входной и выходной информации	аналогичный подраздел отсутствует
•Сведения о входных данных	то же
••Характер, организация и предварительная подготовка входных данных	»
•Сведения о выходных данных	»
••Характер и организация выходных данных	»
••Формат, описание и способ кодирования выходных данных	»
•Описание кодирования информации	»
Настройка программы	Identification of technical or administrative activities that must be done before starting the task (4.7 Information for procedures and tutorials)
•Описание действий по настройке программы	аналогичный подраздел отсутствует
••Настройка на состав технических средств	то же
••Выбор функций	»
••Поясняющие примеры	»
Проверка программы
•Описание способов проверки работоспособности программы	аналогичный подраздел отсутствует
••Контрольные примеры	Examples should illustrate the use of commands (4.8 Information on software commands)
••Методы прогона	аналогичный подраздел отсутствует
••Результаты	то же
Выполнение программы
•Загрузка программы •Способ вызова программы с соответствующего носителя данных •Описание процедур вызова программы	Software installation and de-installation, if performed by the user (4.6 Information for general use of the software)
•Запуск программы	аналогичный подраздел отсутствует
•Входные точки в программу*	Access, or log-on and sign-off the software (4.6 Information for general use of the software)
•Способы передачи управления и параметров данных	аналогичный подраздел отсутствует
•Выполнение программы	то же
••Описание выполняемой функции 1	A brief overview of the purpose of the procedure and definitions or explanations of necessary concepts not elsewhere included (4.7 Information for procedures and tutorials)
••Формат и возможные варианты команд для выполнения функции 1	Navigation through the software to access … functions (4.6 Information for general use of the software) Instructional steps shall be presented in the order of performance (4.7 Information for procedures and tutorials) Documentation shall explain how to interrupt and undo operation during execution of a command and how to restart it, if possible. Documentation shall explain the formats and procedures for user-entered software commands, including required parameters, optional parameters, default options, order of commands, and syntax (4.8 Information on software commands)
••Ответы программы на команды выполнения функции 1	Documentation shall describe how to recognize that the command has successfully executed or abnormally terminated (4.8 Information on software commands)
•Завершение выполнения программы	Navigation through the software … to exit from functions Methods of canceling, interrupting, and restarting operations (4.6 Information for general use of the software)
Дополнительные возможности
•Описание дополнительных функциональных возможностей программы	аналогичный подраздел отсутствует
•Описание применения дополнительных функциональных возможностей программы	то же
Сообщения программы	Relevant warnings, cautions, and notes that apply to the entire procedure (4.7 Information for procedures and tutorials)
•Тексты сообщений, выдаваемых в ходе (настройки, проверки, выполнения) программы	аналогичный подраздел отсутствует
••Описание содержания	то же
••Описание действий, которые необходимо предпринять по этим сообщениям	»

Источник

О стандартах документации

Время на прочтение
4 мин

Количество просмотров 92K

Документация – такая штука, к которой мало кто питает тёплые чувства: скучно, занудно, однообразно. И, тем не менее, иногда не возникает сомнений в её необходимости: ведь кому-то после вас этим пользоваться или, тем паче, модифицировать. И тогда появляется вопрос: как сделать документацию правильно?

Существует тьма статей на тему «как писать документацию», но если вы решили взяться за неё в первый раз, то в новой для вас области не сразу понятно, дело ли пишет автор, или отсебятину выдумывает.

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

Кто-то может сказать «а-а, стандарты! они ещё более адово скучные, чем сама документация!». Ну, не будем врать, есть немного Но если у вас документ в электронном формате – найти необходимое не составляет труда. И кроме того, ну надо же размочить раздел стандарты уже, а то висит пустой, даже обидно.

Наши.

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

ГОСТ Р ИСО 9127-94 «Документация пользователя и информация на упаковке для потребительских программных пакетов» – наиболее приглянувшийся мне стандарт из наших. Довольно кратко (весь документ – около 20 страниц) указаны основные требования к составу и содержанию документации пользователя.
Официальная страница. Скачать PDF.

ГОСТ Р ИСО/МЭК 15910-2002 «Процесс создания документации пользователя программного средства» — стандарт больше отвечает не на вопрос «Что» должно быть в документе, а «Как» должен создаваться документ. Дополнительно есть подробное описание стиля документа с примером – довольно удобная штука для создания шаблона: один раз запариваешься (и забиваешь в шаблон всё: от выравнивания до формата подписей рисунков), а потом клепаешь документы все одного вида, а не с заголовками разного шрифта.
Официальная страница. Скачать PDF.

ГОСТ-ы серии 19.хх – серия ЕСПД, страсть, какая древняя (в среднем, документы созданы в 78-м году), но зато такие же лаконичные, как в ГОСТ 9127, требования ко многим видам документов.
Ознакомиться.

ГОСТ 34.602-89 «Техническое задание на создание автоматизированной системы» — стандарт на ТЗ. Спасибо Jazzist.

Буржуйские.

Не было предела моему возмущению, когда я узнала, что международные стандарты не бесплатные. Это как правила дорожного движения сделать платными. Но в принципе, может и резонно: организации-то не государственные. Хотят – могут и деньги брать за свою работу. К счастью, многие стандарты можно скачать по-привычному, по-пиратски.

IEEE Std 1063-2001 «IEEE Standard for Software User Documentation» — в документе обозначены требования к структуре, содержимому и формату инструкций пользователя.
Официальная страница.

IEEE Std 1016-1998 «IEEE Recommended Practice for Software Design Descriptions» — рекомендации к документам, описывающим архитектуру программного обеспечения, то бишь к техническому описанию.
Официальная страница.
Особливо понравилась табличка-экстракт основного содержания документа (здесь вольный перевод):

ISO/IEC FDIS 18019:2004 «Guidelines for the design and preparation of user documentation for application software» — рекомендации по созданию документации пользователя. Так сказать, советы «хозяйке на заметку». Довольно приятное руководство с большим количеством примеров (имхо, больше подходит для чтения до или в самом начале создания документации, так как подходит к процессу основательно, от самого планирования). Также в приложениях есть чеклисты «что не забыть сделать в процессе разработки документации» и «что должно быть в документе»
Официальная страница.

ISO/IEC 26514:2008 «Requirements for designers and developers of user documentation» — довольно свежий и, судя по содержанию, полезный документ. Но, как раз, видимо, ввиду его свежести, этот стандарт нигде не найти бесплатно. По крайней мере, мне этого сделать не удалось.
Официальная страница.

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

Уточнения, дополнения и полезные ссылки приветствуются)

UPD: очень познавательный комментарий, спасибо lkochetova

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

UPD2: также смотрите статью Документирование по ГОСТ 34* — это просто с подробным разбором отечественных стандартов на проектную документацию.

Источник

Создан 11.02.2005 11:14:22

Когда умирает надежда, приходит отчаяние.

Мудрая латинская поговорка

Каким содержимым наполнять разделы руководства пользователя? Как быть? Главное — не отчаиваться.

Цели и задачи статьи

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

Задачи:

проанализировать существующие стандарты и рекомендации по разработке эксплуатационной программной документации, выявить достоинства и недостатки каждого документа по отдельности;
вывести некую обобщенную структуру руководства пользователя по ГОСТам 19-й системы из имеющегося набора эксплуатационных программных документов;
сравнить ее со структурой, рекомендованной IEEE Std 1063-2001;
а все прочие задачи перекочевали во 2-ю часть статьи…

Вопросы, на которые должно дать ответы руководство пользователя

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

Руководство пользователя: четыре источника и четыре составных части

Располагаем документами:

«метагайдом» Кагарлицкого;
суперсовременным IEEE Std 1063-2001, «IEEE Standard for Software User Documentation»;
классическими отечественными ГОСТами 19-й системы, включающим в себя перечисленные ниже документы «описательного» характера:
- ГОСТ 19.402-78 ЕСПД. Описание программы;
- ГОСТ 19.502-78 ЕСПД. Описание применения. Требования к содержанию и оформлению;
- ГОСТ 19.503-79 ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению;
- ГОСТ 19.504-79 ЕСПД. Руководство программиста. Требования к содержанию и оформлению;
- ГОСТ 19.505-79 ЕСПД. Руководство оператора. Требования к содержанию и оформлению.

Крайняя четверка из перечня — эксплуатационные программные документы.

Манифест Кагарлицкого

(цитаты из манифеста Кагарлицкого)

Начало обнадеживающее.

Руководство пользователя по IEEE Std 1063-2001 «IEEE Standard for Software User Documentation»

This revision provides requirements for the structure, information content, and format of both printed and electronic documentation.

Структура руководства пользователя по IEEE Std 1063-2001

Component	See subclause	Required?
Identification data (package label/title page)	4.3	Yes
Table of contents	5.7.1	Yes, in documents of more than eight pages after identification data
List of illustrations	5.7.2	Optional
Introduction	3.2	Yes
Information for use of the documentation	4.4	Yes
Concept of operations	4.5	Yes
Procedures	4.6, 4.7	Yes (instructional mode)
Information on software commands	4.8	Yes (reference mode)
Error messages and problem resolution	4.9	Yes
Glossary	4.10	Yes, if documentation contains unfamiliar terms
Related information sources	4.11	Optional
Navigational features	5.8	Yes
Index	5.7.3	Yes, if documents of more than 40 pages
Search capability	5.7.4	Yes, in electronic documents

Introduction

Какие сведения должны быть изложены в разделе Introduction согласно IEEE Std 1063-2001? А вот какие

The introduction shall describe the intended audience, scope, and purpose for the document and include a brief overview of the software purpose, functions, and operating environment.

Что ж, замечательно. Структура подразделов Introduction начинает как-то вырисовываться.

Information for use of the documentation

Весьма полезный раздел (в контексте разработки руководства пользователя). Руководство по руководству.

Concept of operations

Концептуальная информация безусловно важна.

Procedures

Task-oriented instructional mode documentation shall include instructions for routine activities that are applied to several functions:

— Software installation and de-installation, if performed by the user

— Orientation to use of the features of the graphical user interface (see 5.6)

— Access, or log-on and sign-off the software

— Navigation through the software to access and to exit from functions

— Data operations (enter, save, read, print, update, and delete)

— Methods of canceling, interrupting, and restarting operations

These common procedures should be presented once to avoid redundancy when they are used in more complex functions.

И пошла конктерика. Молодцы, буржуи!

Information on software commands

Error messages and problem resolution

Выводы по IEEE Std 1063-2001

отсутствие в IEEE Std 1063-2001 четко регламентированной структуры руководства пользователя;
«поверхностность» IEEE Std 1063-2001, отсутствие «широты охвата» и «глубины проработки».

Пользовательские документы по ГОСТ 19 (ЕСПД)

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

Структура разделов описания применения по ГОСТ 19.502-78

Структура разделов руководства системного программиста по ГОСТ 19.503-79

Структура разделов руководства программиста по ГОСТ 19.504-79

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

Выводы по ГОСТам 19.ххх

Обобщенная структура руководства пользователя по ГОСТам 19-й системы

ГОСТ 19.ххх — обобщенная структура разделов руководства	ГОСТ 19.402-78	ГОСТ 19.502-78	ГОСТ 19.503-79	ГОСТ 19.504-79	ГОСТ 19.505-79
Аннотация	*	*	*	*	*
•Назначение документа	*	*	*	*	*
•Краткое изложение основной части документа	*	*	*	*	*
Общие сведения о программе	*		*
•Обозначение и наименование программы	*			*
•Языки программирования, на которых написана программа	*
•Сведения о назначении программы	*	*	*	*	*
••Информация, достаточная для понимания функций программы и ее эксплуатации					*
•••Возможности программы		*
•••Классы решаемых задач	*
••••Описание задач		*
••••Методы решения задач		*
•••Функции, выполняемые программой			*	*
••Описание основных характеристик и особенностей программы		*		*
•••Временные характеристики				*
•••Режим работы				*
•••Средства контроля правильности выполнения и самовосстанавливаемости программы				*
••Ограничения области применения программы		*
•••Сведения о функциональных ограничениях на применение	*
Условия применения программы		*		*	*
•Условия, необходимые для выполнения программы		*	*		*
••Сведения о технических и программных средствах, обеспечивающих выполнение программы			*
•••Требования к техническим средствам	*	*
••••Типы ЭВМ, устройства, используемые при работе программы	*
••••Объем оперативной памяти				*
••••Минимальный и (или) максимальный состав аппаратурных и программных средств					*
••••Требования к составу и параметрам периферийных устройств				*
•••Программное обеспечение, необходимое для функционирование программы	*
••••Требования к программному обеспечению				*
••••Требования к другим программам		*
••••Требования и условия организационного, технического и технологического характера		*
Описание логической структуры	*
•Алгоритм программы	*
•Используемые методы	*
•Сведения о структуре программы	*		*
•Сведения о составных частях программы			*
•Описание функций составных частей	*
•Сведения о связях между составными частями программы	*		*
•Сведения о связях с другими программами	*		*
Сведения о входных и выходных данных		*		*
•Общие характеристики входной и выходной информации		*
•Сведения о входных данных	*	*
••Характер, организация и предварительная подготовка входных данных	*			*
•Сведения о выходных данных	*	*
••Характер и организация выходных данных	*			*
••Формат, описание и способ кодирования выходных данных	*
•Описание кодирования информации				*
Настройка программы			*
•Описание действий по настройке программы			*
••Настройка на состав технических средств			*
••Выбор функций			*
••Поясняющие примеры			*
Проверка программы			*
•Описание способов проверки работоспособности программы			*
••Контрольные примеры			*
••Методы прогона			*
••Результаты			*
Выполнение программы					*
•Загрузка программы •Способ вызова программы с соответствующего носителя данных •Описание процедур вызова программы	*			*	*
•Запуск программы					*
•Входные точки в программу*	*
•Способы передачи управления и параметров данных				*
•Выполнение программы					*
••Описание выполняемой функции 1					*
••Формат и возможные варианты команд для выполнения функции 1					*
••Ответы программы на команды выполнения функции 1					*
•Завершение выполнения программы					*
Дополнительные возможности			*
•Описание дополнительных функциональных возможностей программы			*
•Описание применения дополнительных функциональных возможностей программы			*
Сообщения программы			*	*	*
•Тексты сообщений, выдаваемых в ходе (настройки, проверки, выполнения) программы			*	*	*
••Описание содержания			*	*	*
••Описание действий, которые необходимо предпринять по этим сообщениям			*	*	*

Выводы по обобщенной структуре руководства пользователя по ГОСТ 19.ххх

В то же время, при всей широте охвата, в явном виде отсутствуют:

Software installation and de-installation, if performed by the user;
Orientation to use of the features of the graphical user interface;
Access, or log-on and sign-off the software;
Navigation through the software to access and to exit from functions и многое другое.

Выводы по источникам

Итак, если первые три задачи в целом решены, крайняя задача осталась нерешенной.

Смесь французского с нижегородским

Таблица соответствия ГОСТ 19 и IEEE Std 1063-2001

ГОСТ 19.ххх	IEEE Std 1063-2001
Аннотация	Introduction
	The introduction shall describe the intended audience, scope, and purpose for the document and include a brief overview of the software purpose, functions, and operating environment
•Назначение документа	purpose for the document (Introduction)
•Краткое изложение основной части документа	scope (Introduction)
Общие сведения о программе
•Обозначение и наименование программы	аналогичный подраздел отсутствует
•Языки программирования, на которых написана программа	то же
•Сведения о назначении программы	brief overview of the software purpose (Introduction)
••Информация, достаточная для понимания функций программы и ее эксплуатации	аналогичный подраздел отсутствует
•••Возможности программы	то же
•••Классы решаемых задач	»
••••Описание задач	»
••••Методы решения задач	Documentation shall relate each documented function to the overall process or tasks
•••Функции, выполняемые программой	brief overview of the software … functions (Introduction)
••Описание основных характеристик и особенностей программы	аналогичный подраздел отсутствует
•••Временные характеристики	то же
•••Режим работы	»
•••Средства контроля правильности выполнения и самовосстанавливаемости программы	»
••Ограничения области применения программы	»
•••Сведения о функциональных ограничениях на применение	»
Условия применения программы	If different versions of the software are available for different operating environments, the title page should specify the applicable operating environment(s), including version(s) of hardware, communications, and operating system(s) (4.3. Content of identification data)
•Условия, необходимые для выполнения программы	аналогичный подраздел отсутствует
••Сведения о технических и программных средствах, обеспечивающих выполнение программы	Documentation for the hardware and software environment (4.11 Information on related information sources)
•••Требования к техническим средствам	аналогичный подраздел отсутствует
••••Типы ЭВМ, устройств, используемые при работе программы	то же
••••Объем оперативной памяти	»
••••Минимальный и (или) максимальный состав аппаратурных и программных средств	»
••••Требования к составу и параметрам периферийных устройств	»
•••Программное обеспечение, необходимое для функционирование программы	brief overview of the … operating environment (Introduction)
••••Требования к программному обеспечению	аналогичный подраздел отсутствует
••••Требования к другим программам	то же
•••Требования и условия организационного, технического и технологического характера	»
Описание логической структуры
•Алгоритм программы	algorithms (4.5 Concept of operations)
•Используемые методы	using such methods as a visual or verbal overview of the process or workflow (4.5 Concept of operations)
•Сведения о структуре программы	аналогичный подраздел отсутствует
•Сведения о составных частях программы	то же
•Описание функций составных частей	»
•Сведения о связях между составными частями программы	»
•Сведения о связях с другими программами	»
Сведения о входных и выходных данных
•Общие характеристики входной и выходной информации	аналогичный подраздел отсутствует
•Сведения о входных данных	то же
••Характер, организация и предварительная подготовка входных данных	»
•Сведения о выходных данных	»
••Характер и организация выходных данных	»
••Формат, описание и способ кодирования выходных данных	»
•Описание кодирования информации	»
Настройка программы	Identification of technical or administrative activities that must be done before starting the task (4.7 Information for procedures and tutorials)
•Описание действий по настройке программы	аналогичный подраздел отсутствует
••Настройка на состав технических средств	то же
••Выбор функций	»
••Поясняющие примеры	»
Проверка программы
•Описание способов проверки работоспособности программы	аналогичный подраздел отсутствует
••Контрольные примеры	Examples should illustrate the use of commands (4.8 Information on software commands)
••Методы прогона	аналогичный подраздел отсутствует
••Результаты	то же
Выполнение программы
•Загрузка программы •Способ вызова программы с соответствующего носителя данных •Описание процедур вызова программы	Software installation and de-installation, if performed by the user (4.6 Information for general use of the software)
•Запуск программы	аналогичный подраздел отсутствует
•Входные точки в программу*	Access, or log-on and sign-off the software (4.6 Information for general use of the software)
•Способы передачи управления и параметров данных	аналогичный подраздел отсутствует
•Выполнение программы	то же
••Описание выполняемой функции 1	A brief overview of the purpose of the procedure and definitions or explanations of necessary concepts not elsewhere included (4.7 Information for procedures and tutorials)
••Формат и возможные варианты команд для выполнения функции 1	Navigation through the software to access … functions (4.6 Information for general use of the software) Instructional steps shall be presented in the order of performance (4.7 Information for procedures and tutorials) Documentation shall explain how to interrupt and undo operation during execution of a command and how to restart it, if possible. Documentation shall explain the formats and procedures for user-entered software commands, including required parameters, optional parameters, default options, order of commands, and syntax (4.8 Information on software commands)
••Ответы программы на команды выполнения функции 1	Documentation shall describe how to recognize that the command has successfully executed or abnormally terminated (4.8 Information on software commands)
•Завершение выполнения программы	Navigation through the software … to exit from functions Methods of canceling, interrupting, and restarting operations (4.6 Information for general use of the software)
Дополнительные возможности
•Описание дополнительных функциональных возможностей программы	аналогичный подраздел отсутствует
•Описание применения дополнительных функциональных возможностей программы	то же
Сообщения программы	Relevant warnings, cautions, and notes that apply to the entire procedure (4.7 Information for procedures and tutorials)
•Тексты сообщений, выдаваемых в ходе (настройки, проверки, выполнения) программы	аналогичный подраздел отсутствует
••Описание содержания	то же
••Описание действий, которые необходимо предпринять по этим сообщениям	»

О стандартах документации

Время на прочтение
4 мин

Количество просмотров 90K

Наши.

ГОСТ 34.602-89 «Техническое задание на создание автоматизированной системы» — стандарт на ТЗ. Спасибо Jazzist.

Буржуйские.

Уточнения, дополнения и полезные ссылки приветствуются)

UPD: очень познавательный комментарий, спасибо lkochetova

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

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

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

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

Международный стандарт МЭК / IEEE 82079-1 находит все более широкое применение

Минувшей весной Европейский комитет по электротехнической стандартизации (Comité Européen de Normalisation Electrotechnique; CENELEC) рекомендовал европейским организациям по стандартизации в течение шести месяцев создать национальные стандарты на основе пересмотренного и утвержденного в минувшем году документа МЭК / IEEE 82079-1 «Подготовка информации для пользователей продуктов (инструкций по применению) — Часть 1: Принципы и общие требования».

Пересмотр стандарта проводился техническим комитетом 3 (документация, графические символы и представление технической информации) Международной электротехнической комиссии (International Electrical Commission; IEC; МЭК) при поддержке Института инженеров по электротехнике и радиоэлектронике (Institute of Electrical and Electronics Engineers; IEEE) и Международной организации по стандартизации (International Organization for Standardization; ISO; ИСО).

Как отмечают авторы МЭК / IEEE 82079-1, этот стандарт предоставляет сторонам, ответственным за создание инструкций, исчерпывающие сведения о потребностях различных групп пользователей. Руководствуясь рекомендациями МЭК / IEEE 82079-1, разработчики мануалов помогут конечным потребителям использовать продукты более безопасно и эффективно.

Какие области охватывает стандарт МЭК / IEEE 82079-1?

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

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

Кому будет полезен этот стандарт?

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

Его авторы подчеркивают необходимость того, чтобы разные стороны, участвующие в представлении информации об использовании, применяли МЭК / IEEE 82079-1 к своим продуктам для потребителей. Кроме того, отмечается важность надлежащего предоставления информации, необходимой для безопасного и эффективного использования продукта.

Особо подчеркивается, что поставщики продуктов и владельцы брендов, применяющие этот стандарт по отношению к своей продукции, смогут получить существенную выгоду от внедрения МЭК / IEEE 82079-1, поскольку это позволит ограничить риски, связанные с недостаточностью информации для пользователей.

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

Качество информации для пользователей — очень важный момент. Многим из нас в какой-то момент своей жизни было непросто понять пользовательские руководства. Исчерпывающий список проблем, с которыми сталкиваются потребители при работе с инструкциями, был определен и проанализирован в исследовании, проведенном в 2009 году Советом по потребительским вопросам при Немецком институте по стандартизации (Deutsches Institut für Normung; DIN).

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

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

Какие типы продуктов могут быть охвачены стандартом МЭК / IEEE 82079-1?

Документ МЭК / IEEE 82079-1 дает рекомендации по подготовке информации для пользователей любых продуктов, охватываемых сферой деятельности трех организаций, которые разработали данный стандарт, — будь то электрические, неэлектрические или программные решения.

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

Как следует готовить информацию для пользователей на базе МЭК / IEEE 82079-1?

Стандарт МЭК / IEEE 82079-1 устанавливает принципы выбора типа контента, его структуры, а также носителей и формата информации для конечных пользователей. Он дает рекомендации относительно профессиональных компетенций авторов инструкций, процессов их разработки, публикации и актуализации. Эти принципы касаются качества контента, целей представления информации для пользователей и процессов управления информацией. Авторами рассматриваются следующие аспекты:

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

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

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

Стандарт МЭК / IEEE 82079-1 предоставляет подробные рекомендации относительно эмпирической оценки информации для пользователей, позволяющие заинтересованным сторонам определить, насколько она понятна. Кроме того, его авторы дают рекомендации на тему обеспечения простого поиска, удобной навигации и однозначного понимания содержания мануала.

Существует множество видов предоставления справочной информации пользователю – это и FAQ (frequently asked questions, часто задаваемые вопросы) и онлайн справка и руководство пользователя (user guide) и популярные сегодня подсказки (coachmarks, см. пример ниже), обучающие видео и другие.

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

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

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

1. Стандарты

Часто бывает нужно написать документ, который бы удовлетворял требованиям действующих стандартов. Это могут быть:

IEEE Std 1063-2001, «IEEE Standard for Software User Documentation»;
ГОСТ 19:
- ГОСТ 19.402-78 ЕСПД. Описание программы;
- ГОСТ 19.502-78 ЕСПД. Общее описание. Требования к содержанию и оформлению;
- ГОСТ 19.503-79 ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению;
- ГОСТ 19.504-79 ЕСПД. Руководство программиста. Требования к содержанию и оформлению;
- ГОСТ 19.505-79 ЕСПД. Руководство оператора. Требования к содержанию и оформлению.

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

Также может оказаться полезной книга Юрия Кагарлицкого MetaGuide. Руководство для разработчиков технической документации к программному обеспечению.

2. Структура

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

Хорошее руководство пользователя должно содержать:

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

Также руководство пользователя может содержать:

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

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

3. Пользователи

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

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

Уважайте пользователей системы, не пишите инструкции в пренебрежительном стиле.

4. Особенности изложения

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

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

Для составления хорошего документа пригодятся знания грамматики и немного психологии.

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

Хорошо: In File menu, select Save item.
Хуже: Select Save item from File menu.

4.2 Используйте повелительное наклонение, не употребляйте вежливые обороты (please, could и т.д.) — излишняя вежливость именно здесь будет помехой.

Хорошо: Click Logout to log out current user account from the system.

Хуже: It is needed to click Logout to log out current user account from the system.

Хуже: If user wants to log out current user account from the system (s)he needs to click Logout.

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

Хорошо:
To create project:

Click the Create button on toolbar.
On the Create Project overlay fill in all mandatory fields.
Click the Save button to save the project.

Хуже: To create project click the Create button on toolbar, on the Create Project overlay fill in all mandatory fields, click the Save button to save the project.

4.4 Не используйте будущее или прошлое время. Например, часто встречаются руководства, в которых реакция системы на действие пользователя передается фразами, сформулированными в будущем времени. У ПО нет прошлого или будущего: всё случается в настоящем как прямой результат конкретного действия пользователя. Как только событие случается, ПО реагирует.

Хорошо: When user clicks the Start button, the program starts the process.

Хуже: When user clicks the Start button, the program will start the process.

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

Например, глагол «press» означает нажатие клавиши на клавиатуре, а «click» – нажатие кнопки или значка в окне программы при помощи мыши, а «hit» вообще является жаргонным словом.

Разумеется, орфографические ошибки недопустимы.

4.6 Не используйте синонимы для одного и того же термина. В IT литературе на английском (или любом другом) языке есть стандартный набор глаголов, обозначающих действия (click, double-click, select, type, press и т.д.) и такой же стандартный набор названий элементов управления. Определитесь с терминологией и придерживайтесь ее в рамках всего документа.

Например, не допускайте, чтобы в одной части документа выпадающий список назывался dropdown, а в другой точно такой же элемент – combobox или dropdown list. Это путает пользователя.

4.7 Разумно используйте сокращения и исключите жаргон.

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

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

5. Внешний вид

5.1 Продумайте стиль документа. Это может быть корпоративный шаблон или цветовая схема ПО или специально сделанный для документа дизайн.

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

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

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

6. Поддержка

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

Заключение

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

Помните главное: документ должен помогать пользователям.

Статью подготовила

Nadia Тарасюк Надежда, участник сообщества analyst.by,

аналитик с 6-летним опытом в сфере.

Источник