Похожие публикации

Рабочая программа по курсу «Русский язык» (2)
Рабочая программа
Рабочая программа по курсу «Русский язык» образовательной области «Филология» разработана на основе Примерной программы начального общего образования ...полностью>>

1. 1 Кольца резиновые уплотнительные гост 9833-73
Реферат
ООО «Управляющая компания «Система-Сервис»» (бывшая Альметьевская центральная база производственного обслуживания по прокату и ремонту электропогружны...полностью>>

1. 1 Кольца резиновые уплотнительные гост 9833-73
Реферат
ООО «Управляющая компания «Система-Сервис»» (бывшая Альметьевская центральная база производственного обслуживания по прокату и ремонту электропогружны...полностью>>

1. 1 Кольца резиновые уплотнительные гост 9833-73
Реферат
ООО «Управляющая компания «Система-Сервис»» (бывшая Альметьевская центральная база производственного обслуживания по прокату и ремонту электропогружны...полностью>>



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

Как писать руководство пользователя? Часть I

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

Где взять структуру разделов руководства пользователя? С руководствами на изделия (руководство по эксплуатации по ГОСТ 2.601-95) и на автоматизированные системы (руководство пользователя по РД 50-34.698-90) все более или менее ясно. А вот руководство пользователя программы в ГОСТ 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», но не предлагает явной структуры руководства пользователя до рекомендованного четвертого уровня вложенности.

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

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

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

  • «поверхностность» IEEE Std 1063-2001, отсутствие «широты охвата» и «глубины проработки».

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

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