Гост 19 Руководство Пользователя

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

/ МПО_для_заочников_ч2 / Лекции_МПО_ч2 / Руководство пользователя

Руководство пользователя как программная (эксплуатационная) документация пользователя

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

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

Документация. программная/эксплуатационная/документация пользователя

Предмет. программа, программный компонент комплекса илисистемы

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

Задачи. обеспечить пользователям возможность в полном объеме самостоятельно освоить и применять программу

Руководящими стандартами для создания документа Руководство пользователя могут являться как РД 50-34.698-90 в п.п. 3.4. «Руководство пользователя». так и ГОСТ 19.505-79 «Руководство оператора. Требования к содержанию и оформлению».

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

Условия применения системы;

Подготовка системы к работе;

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

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

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

Условия применения системы

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

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

Квалификация пользователя – данный подраздел должен содержать требования к навыкам и знаниям пользователя (пример: «Пользователи должны обладать умениями работать с операционной системой Windows» );

Подготовка системы к работе

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

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

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

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

«4.1 Согласование проекта

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

Автор проекта создает запись в Системе и прикрепляет пакет необходимой документации, далее проект передается на согласование руководящими лицами. Руководители после ознакомления с проектом могут подтвердить его или отправить на доработку Автору.

4.1.1 Создание проекта

Для того чтобы создать Проект необходимо на панели «…» нажать на кнопку «…» и в появившейся форме заполнить следующие поля:

Следующие поля заполняются автоматически:

Дата создания проекта – текущая дата;

Автор – ФИО и должность автора проекта.»

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

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

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

Методика и стиль изложения руководства пользователей

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

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

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

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

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

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

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

Как писать руководство пользователя? Часть 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:

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, отсутствие «широты охвата» и «глубины проработки».

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

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

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

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

ГОСТ 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 допускает «вводить дополнительные разделы или объединять отдельные разделы», а также «вводить новые». Согласно п. 2.6 ГОСТ 19.101-77 допускается объединять отдельные виды эксплуатационных документов. Необходимость объединения этих документов указывается в техническом задании. Объединенному документу присваивают наименование и обозначение одного из объединяемых документов.

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

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

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

В табличке сведены и * отмечены разделы, присутствующие в каждом отдельном документе.

ГОСТ 19 - обобщенная структура разделов руководства

Выводы по обобщенной структуре руководства пользователя по ГОСТ 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 Как писать руководство пользователя? Часть II

Об этом - в очередной статье.

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

Цели и задачи

Некоторые маститые технические писатели возмущены приверженностью автора к ГОСТ 7.32, структура разделов которого предусматривает как цели, так и задачи.

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

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

установить «степень опциональности» отдельных разделов руководства;

избавиться от «старообразности» заголовков отдельных разделов руководства;

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

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

Разъяснения к задачам

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

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

вопросы «а почему необходима именно такая структура руководства пользователя, а не иная?» так и не последовали.

Руководство пользователя: из любви к процессам

- Поручик, Вы любите детей?

- Никак нет-с. Но сам процесс.

Как ни прискорбно, но задача освещения процессов (процедур) разработки технической документации в первой части статьи не ставилась. Ибо о процессах имеется отдельная статья - «Автоматизация разработки технической документации ».

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

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

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

В чем же причина отсутствия интереса к структуре руководства пользователя? Вероятно, многие г-да технические писатели считают, что:

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

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

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

Руководство пользователя: рекомендации манифеста

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

Совершенно верно. В документах описательного характера всегда следует двигаться от общего к частному. Дедукция, панимаш.

«Общая логика изложения навязывает многоуровневую рубрикацию: более общим уровням описания продукта соответствуют более крупные главы и разделы, более частным и конкретным - более мелкие, подчиненные ».

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

«Соображения удобства не отменяют логики изложения, а дополняют ее. Собственно говоря, логичное, хорошо структурированное изложение хорошо усваивается и позволяет безошибочно ориентироваться в нем».

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

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

Вот она, забота о пользователе! Структура разделов руководства пользователя является определяющей при разработке пользовательских руководств.

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

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

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

Начнем с того, что получше. Исследуем (поверхностно) образцы творений «бригады» технических писателей, плодотворно работающих в известной российской софтверной компании.

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

Структуры руководств пользователей - пример получше

На рисунке - структуры заголовков 1 уровня руководств пользователя двух равноуровневых «подсистем» единого программного комплекса.

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

Структура руководства пользователя - пример похуже

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

Простые формальные замечания:

Предисловие расположено после Оглавления ;

Предисловие (по сути - Введение) - заголовок 1 уровня, Заключение - заголовок 2 уровня;

Гиперссылки не имеют никакого отношения к Навигации и существуют сами по себе;

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

Учет запчастей и ремонтов явно не входит в Задачи автотранспортной компании (интересно, кто же должен заниматься учетом запчастей и ремонтов?);

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

Выводы

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

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

некоторое соответствие требованиям стандартов на программную документацию.

Но ничего подобного не наблюдается.

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

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

Автор образца не знаком с п. 1 ст. 10. Закона «О защите прав потребителей» - «Изготовитель (исполнитель, продавец) обязан своевременно предоставлять потребителю необходимую и достоверную информацию о товарах (работах, услугах), обеспечивающую возможность их правильного выбора».

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

«Если навести. » - ух, каков стиль! Без старого Циреса, которого «завалил» Беня Крик, пользователю никак не обойтись;

служил участок гиперссылкой (служил Гаврила хлебопеком);

указатели чудесным образом «превращаются» в «персты» (далее - «пятерни», «лапы»). А брюки - в элегантные шорты;

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

при отсутствии участка гиперссылка не работает (разумеется).

Неудобно называть автора шедевра просто «техническим писателем всех времен и народов» и т.д. Но бросать тень на автора, наносить ущерб имиджу компании, в коей он работает - уж больно неэтично.

А что скажут медики? «. указанные симптомы в течение длительного времени наблюдались лечащим врачом у больного К. 56 лет». Медицинская этика всегда была и остается на высоте.

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

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

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

Независимость структуры разделов руководства пользователя от «новизны» программного продукта

Цитата из манифеста:

«В то же время не следует думать, что стандартная структура - это готовый бланк, в который только вписываются сведения о конкретном продукте. Каждый новый продукт - это своего рода вызов стандарту; он требует втиснуть новые реалии в типовые ячейки, что зачастую вызывает проблемы».

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

Какие новые реалии автор манифеста не в силах втиснуть в «ячейки» типовой структуры? Сформировавшийся за последние пятнадцать лет графический пользовательский интерфейс? Да запросто. См. учебно-тренировочное «Руководство оператора по ГОСТ 19.505-79 ».

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

Для тех, кто не в курсе. Терменвокс - первый в мире электромузыкальный инструмент, изобретенный в России в начале прошлого века Львом Сергеевичем Терменом. Звукоизвлечение было основано на изменении емкости связки «антенна терменвокса - человеческое тело». Иными словами, человек определенным образом «гнул пальцы» перед антенной, емкость изменялась, изменялась частота задающего генератора терменвокса (высота воспроизводимого звука).

Возможности инструмента демонстрировались в Кремле В.И. Ленину. Старые большевики утверждают, что Владимир Ильич моментально освоил технику игры и самостоятельно довел мелодию, начатую Терменом, до конца.

Так вот, возможно ли втиснуть описание бесконтактного пользовательского «терменфейса» в типовые ячейки структуры? Без особых проблем. Фрагмент руководства из будущего: «. для печати документа следует сложить пальцы фигой» (изображения «лап» и «перстов» из «руководств» Г, 60 лет, окажутся весьма кстати).

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

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

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

для конкретного Заказчика (З);

для «дома и офиса» - для Пользователя (П).

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

Н - раздел настоятельно рекомендуется ;

Р - раздел рекомендуется ;

О - раздел опционален .

Почему такое зверство? А есть п. 3 ст. 10 Закона «О защите прав потребителей» - «. исчерпывающая информация о товаре доводится Изготовителем до сведения потребителя в технической документации. прилагаемой к товарам. ». А программа - это ведь товарная продукция (для пользователя-Потребителя) и продукция производственно-технического назначения (для Заказчика).

Руководство пользователя: избавление от «старообразности» заголовков разделов

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

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

Компромиссный вариант структуры руководства пользователя должен устраивать «и наших, и ваших»:

«наших» - удовлетворять требованиям ГОСТ 19 серии (здравого смысла );

рекомендации IEEE Std 1063-2001 (для любителей всего «модненького-заграничненького»);

рекомендации манифеста Кагарлицкого (для любителей изящного, изысканного построения фраз);

фантазии «технических писателей всех времен и народов», коим техническая документация, разработанная согласно требований «увесистого тома ГОСТ 19», кажется «составленной непонятно и дурно».

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

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

Цифры 1, 2 и т.д. соответствуют уровню вложенности заголовка.

Наименование раздела (подраздела)

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

Назначение документа

Настоящее руководство предназначено для ознакомления пользователя с техническими характеристиками и функциональными возможностями программы FineDeveloper™ и так далее. Что писать - ясно.

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

Краткое изложение основной части документа

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

В пользовательском документе можно было бы «объединить» с предыдущим при публикации, спрятав заголовок подраздела.

Общие сведения о программе

В IEEE Std 1063-2001 соотвествует разделу Scope. Можно назвать Обзором.

Обозначение и наименование программы

Наименование программы - «Автоматизированный программный комплекс разработки технической документации».

Обозначение программы - FineDeveloper™.

Языки программирования, на которых написана программа

Раздел на усмотрение Заказчика.

Назначение программы

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

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

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

Возможности программы

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

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

Классы решаемых задач

Классифицировать решаемые задачи способен только Заказчик. А если неспособен, тогда уровни вложенных подразделов стоит обозначить не 4, а 3.

Описание задач

Следует исходить из возможностей, если техническое задание на программу отсутствует. А задача программы FineDeveloper™ такова:

имеется техническая информация;

имеется нормативно-техническая документация (ГОСТы, IEEE и пр.);

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

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

Методы решения задач

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

Пользователю вряд ли интересны методы решения задач. А вот Заказчик может заинтересоваться.

Функции, выполняемые программой

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

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

Описание основных характеристик и особенностей программы

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

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

Временные характеристики

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

Режим работы

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

Нет технического задания - придумаем свои режимы:

режим получения и обработки поступающей информации;

режим формирования технической документации;

режим локализации технической документации;

режим публикации технической документации.

Средства контроля правильности выполнения и самовосстанавливаемости программы

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

Ограничения области применения программы

Показать надо обязательно. Ибо Закон «О защите прав потребителей» имеется. Программа не может и не должна делать то, к чему не предназначена.

Сведения о функциональных ограничениях на применение

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

Условия применения программы

Обязательно. Не будет программа выполняться на ноутбуке при пятидесятиградусном морозе.

Условия, необходимые для выполнения программы

А вот при температуре от плюс 5 до плюс 35 °C будет. Следует указать.

Сведения о технических и программных средствах, обеспечивающих выполнение программы

Как минимум, потребуются:

Руководства, Инструкции, Бланки

Поиск

Новые файлы

Описание

ГОСТ -79 ЕСПД

Видео

Другие статьи

Руководство администратора

Структура руководства пользователя по стандартам

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