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

Практическая работа №13

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

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

Теоретические
сведения.

Руководство
пользователя (user guide или user
manual), руководство по эксплуатации, руководство
оператора — документ, назначение которого — предоставить людям помощь
в использовании некоторой системы. Документ входит в состав технической
документации на систему и, как правило,
подготавливается техническим писателем.

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

Содержание

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

·       
Аннотацию, в
которой приводится краткое изложение содержимого документа и его назначение

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

·       
Страницу
содержания

·       
Главы,
описывающие, как использовать, по крайней мере, наиболее важные функции
системы

·       
Главу, описывающую
возможные проблемы и пути их решения

·       
Часто
задаваемые вопросы и ответы
на них

·       
Где
ещё найти информацию по предмету, контактная информация

·       
Глоссарий и, в
больших документах, предметный указатель

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

Стандарты

Структура и
содержание документа Руководство пользователя автоматизированной
системы регламентированы подразделом 3.4 документа РД 50-34.698-90. Структура и
содержание документов Руководство оператора, Руководство
программиста, Руководство системного программиста регламентированы
ГОСТ 19.505-79, ГОСТ 19.504-79 и ГОСТ 19.503-79 соответственно.

·       
Комплекс
стандартов и руководящих документов на автоматизированные системы (ГОСТ 34)

·     РД
50-34.698-90 АВТОМАТИЗИРОВАННЫЕ СИСТЕМЫ. ТРЕБОВАНИЯ К СОДЕРЖАНИЮ ДОКУМЕНТОВ

·       
Единая система конструкторской документации (ЕСКД)
определяет документ «Руководство по эксплуатации» и другие документы:

·     ГОСТ
2.601-2013 Эксплуатационные документы

·     ГОСТ
2.610-2006 Правила выполнения эксплуатационных документов

·       
Единая
система программной документации (ЕСПД)
определяет документы «Руководство оператора», «Руководство по техническому обслуживанию»
и их структуру:

·     ГОСТ
19.101-77 Виды программ и программных документов

·     ГОСТ
19.105-78 Общие требования к программным документам

·     ГОСТ
19.505-79 Руководство оператора. Требования к содержанию и оформлению

·     ГОСТ
19.508-79 Руководство по техническому обслуживанию. Требования к содержанию и
оформлению.

Руководство
пользователя согласно требованиям ГОСТ

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

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

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

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

ü Назначение
системы;

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

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

ü Описание операций;

ü Аварийные
ситуации.

Назначение системы

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

Пример:

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

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

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

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

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

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

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

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

Описание
операций

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

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

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

Пример:

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

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

Наименование
проекта;

Описание
проекта;

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

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

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

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

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

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

Аварийные
ситуации

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

Ниже представлен пример (образец)
документа «Руководство пользователя«, разработанного на
основании методических указаний РД
50-34.698-90.

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

Для формирования руководства пользователя
в качестве примера был взят инструмент Oracle Discoverer информационно-аналитической
системы «Корпоративное хранилище данных».

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

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

1.     
Введение.

2.     
Назначение и
условия применения.

3.     
Подготовка к
работе.

4.     
Описание операций.

5.     
Аварийные
ситуации.

6.     
Рекомендации по
освоению.

1. Введение

В разделе «Введение»
указывают:

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

2.     
краткое
описание возможностей;

3.     
уровень
подготовки пользователя;

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

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

Требования настоящего документа
применяются при:

·  предварительных комплексных
испытаниях;

·  опытной эксплуатации;

·  приемочных испытаниях;

·  промышленной эксплуатации.

1.2. Краткое описание возможностей

Информационно-аналитическая
система Корпоративное Хранилище Данных (ИАС КХД) предназначена для оптимизации
технологии принятия тактических и стратегических управленческих решений
конечными бизнес-пользователями на основе информации о всех аспектах
финансово-хозяйственной деятельности Компании.

ИАС КХД предоставляет возможность
работы с регламентированной и нерегламентированной отчетностью.

При работе с отчетностью
используется инструмент пользователя Oracle Discoverer Plus, который
предоставляет следующие возможности:

·  формирование табличных и
кросс-табличных отчетов;

·  построение различных диаграмм;

·  экспорт и импорт результатов
анализа;

·  печать результатов анализа;

·  распространение результатов
анализа.

1.3. Уровень подготовки
пользователя

Пользователь ИАС КХД должен иметь
опыт работы с ОС MS Windows (95/98/NT/2000/XP), навык работы с ПО Internet
Explorer, Oracle Discoverer, а также обладать следующими знаниями:

·  знать соответствующую предметную
область;

·  знать основы многомерного анализа;

·  понимать многомерную модель
соответствующей предметной области;

·  знать и иметь навыки работы с
аналитическими приложениями.

Квалификация пользователя должна
позволять:

·  формировать отчеты в Oracle
Discoverer Plus;

·  осуществлять анализ данных.

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

·  Информационно-аналитическая
система «Корпоративное хранилище данных». ПАСПОРТ;

·  Информационно-аналитическая
система «Корпоративное хранилище данных». ОБЩЕЕ ОПИСАНИЕ СИСТЕМЫ.

2. Назначение и условия применения
Oracle Discoverer Plus

В разделе «Назначение и
условия применения» указывают:

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

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

Oracle Discoverer Plus в составе
ИАС КХД предназначен для автоматизации подготовки, настройки отчетных форм по
показателям деятельности, а также для углубленного исследования данных на
основе корпоративной информации хранилища данных.

Работа с Oracle Discoverer Plus в
составе ИАС КХД возможна всегда, когда есть необходимость в получении
информации для анализа, контроля, мониторинга и принятия решений на ее основе.

Работа с Oracle Discoverer Plus в
составе ИАС КХД доступна всем пользователям с установленными правами доступа.

3. Подготовка к работе

В разделе «Подготовка к работе»
указывают:

1.     
состав и
содержание дистрибутивного носителя данных;

2.     
порядок
загрузки данных и программ;

3.     
порядок
проверки работоспособности.

3.1. Состав и содержание
дистрибутивного носителя данных

Для работы с ИАС КХД необходимо
следующее программное обеспечение:

1.     
Internet
Explorer (входит в состав операционной системы Windows);

2.     
Oracle
JInitiator устанавливается автоматически при первом обращении пользователя к
ИАС КХД.

3.2. Порядок загрузки данных и
программ

Перед началом работы с ИАС КХД на
рабочем месте пользователя необходимо выполнить следующие действия:

1.     
Необходимо
зайти на сайт ИАС КХД ias-dwh.ru.

2.     
Во время
загрузки в появившемся окне «Предупреждение о безопасности», которое
будет содержать следующее: ‘Хотите установить и выполнить «Oracle JInitiator»
…’ Нажимаем на кнопку «Да».

3.     
После чего
запуститься установка Oracle JInitiator на Ваш компьютер. Выбираем кнопку Next
и затем OK.

3.3. Порядок проверки
работоспособности

Для проверки доступности ИАС КХД с
рабочего места пользователя необходимо выполнить следующие действия:

1.     
Открыть
Internet Explorer, для этого необходимо кликнуть по ярлыку «Internet Explorer»
на рабочем столе или вызвать из меню «Пуск».

2.     
Ввести в
адресную строку Internet Explorer адрес: ias-dwh.ru и нажать «Переход».

3.     
В форме аутентификации
ввести пользовательский логин и пароль. Нажать кнопку «Далее».

4.     
Убедиться, что
в окне открылось приложение Oracle Discoverer Plus.

В случае если приложение Oracle
Discoverer Plus не запускается, то следует обратиться в службу поддержки.

4. Описание операций

В разделе «Описание
операций» указывают:

1.     
описание всех
выполняемых функций, задач, комплексов задач, процедур;

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

Для каждой операции обработки
данных указывают:

1.     
наименование;

2.     
условия, при
соблюдении которых возможно выполнение операции;

3.     
подготовительные
действия;

4.     
основные
действия в требуемой последовательности;

5.     
заключительные
действия;

6.     
ресурсы, расходуемые
на операцию.

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

4.1. Выполняемые функции и задачи

Oracle Discoverer Plus в составе
ИАС КХД выполняет функции и задачи, приведенные в таблице ниже:

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

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

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

Задача:
«Визуализация отчетности»

Операция 1: Регистрация на портале
ИАС КХД

Условия,
при соблюдении которых возможно выполнение операции:

1.     
Компьютер
пользователя подключен к корпоративной сети.

2.     
Портал ИАС КХД
доступен.

3.     
ИАС КХД
функционирует в штатном режиме.

Подготовительные
действия:

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

Основные
действия в требуемой последовательности:

1.     
На иконке «ИАС
КХД» рабочего стола произвести двойной щелчок левой кнопкой мышки.

2.     
В открывшемся
окне в поле «Логин» ввести имя пользователя, в поле «Пароль» ввести пароль пользователя.
Нажать кнопку «Далее».

Заключительные
действия:

Не требуются.

Ресурсы,
расходуемые на операцию:

15-30 секунд.

Операция 2: Выбор отчета

Условия,
при соблюдении которых возможно выполнение операции:

Успешная регистрация на Портале
ИАС КХД.

Подготовительные
действия:

Не требуются.

Основные
действия в требуемой последовательности:

1. В появившемся окне «Мастер
создания рабочих книг» поставить точку напротив пункта «Открыть существующую
рабочую книгу».

2. Выбрать нужную рабочую книгу и
нажать кнопку «Откр.»:

Заключительные действия:

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

Ресурсы,
расходуемые на операцию:

15 секунд.

Задача:
«Формирование табличных и графических форм отчетности»

Заполняется по аналогии.

5. Аварийные ситуации

В разделе «Аварийные
ситуации» указывают: 1. действия в случае несоблюдения условий выполнения
технологического процесса, в том числе при длительных отказах технических
средств; 2. действия по восстановлению программ и/или данных при отказе
магнитных носителей или обнаружении ошибок в данных; 3. действия в случаях
обнаружении несанкционированного вмешательства в данные; 4. действия в других
аварийных ситуациях.

В случае возникновения ошибок при
работе ИАС КХД, не описанных ниже в данном разделе, необходимо обращаться к
сотруднику подразделения технической поддержки ДИТ (HelpDesk) либо к
ответственному Администратору ИАС КХД.

Класс ошибки	Ошибка	Описание ошибки	Требуемые действия пользователя при возникновении ошибки
Портал ИАС КХД	Сервер не найден. Невозможно отобразить страницу	Возможны проблемы с сетью или с доступом к порталу ИАС КХД.	Для устранения проблем с сетью обратиться к сотруднику подразделения технической поддержки (HelpDesk). В других случаях к администратору ИАС КХД.
Ошибка: Требуется ввести действительное имя пользователя	При регистрации на портале ИАС КХД не введено имя пользователя.	Ввести имя пользователя.
Ошибка: Требуется ввести пароль для регистрации	При регистрации на портале ИАС КХД не введен пароль.	Ввести пароль.
Ошибка: Сбой аутентификации. Повторите попытку	Неверно введено имя пользователя или пароль, либо такая учетная запись не зарегистрирована.	Нужно повторить ввод имени пользователя и пароля, однако после третей неудачной попытки регистрации учетная запись блокируется. Если учетная запись заблокирована, нужно обратиться к администратору ИАС КХД.
Сбой в электропитании рабочей станции	Нет электропитания рабочей станции или произошел сбой в электропитании.	Рабочая станция выключилась или перезагрузилась.	Перезагрузить рабочую станцию. Проверить доступность сервера ИАС КХД по порту 80, выполнив следующие команды: — нажать кнопку «Пуск» — выбрать пункт «Выполнить» — в строке ввода набрать команду telnet ias_dwh.ru 80 — если открылось окно Telnet, значит соединение возможно. Повторить попытку подключения (входа) в ИАС КХД
Сбой локальной сети	Нет сетевого взаимодействия между рабочей станцией и сервером приложений ИАС КХД	Отсутствует возможность начала (продолжения) работы с ИАС КХД. Нет сетевого подключения к серверу ИАС КХД	Перезагрузить рабочую станцию. Проверить доступность сервера ИАС КХД по порту 80, выполнив следующие команды: — нажать кнопку «Пуск» — выбрать пункт «Выполнить» — в строке ввода набрать команду telnet ias_dwh.ru 80 — если открылось окно Telnet, значит соединение возможно. После восстановления работы локальной сети повторить попытку подключения (входа) в ИАС КХД.

6. Рекомендации по освоению

В разделе «Рекомендации по
освоению» указывают рекомендации по освоению и эксплуатации, включая
описание контрольного примера, правила его запуска и выполнения.

Рекомендуемая литература:

·  Oracle® Business Intelligence Discoverer
Viewer User’s Guide

·  Oracle® Business Intelligence Discoverer
Plus User’s Guide

Рекомендуемые курсы обучения:

·  Discoverer 10g: Создание запросов
и отчетов

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

Ход
работы:

Задание 1.
Изучите
свой вариант руководства пользователя. Опишите его по следующему плану:

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

2)
основные технические характеристики продукта;

3)
основные разделы руководства пользователя (название раздела и краткое его
описание)

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

Сделайте
вывод
о проделанной работе.

Контрольные
вопросы:

1) Дайте
определения понятиям «руководство пользователя», «инструкция по эксплуатации»

2) Какие
основные разделы должно содержать руководство пользователя?

3) Какие
стандарты описывают Руководство пользователя Руководство оператора, Руководство
программиста, Руководство системного программиста?

4) Что
описывает раздел «назначение системы»?

5) Что
указывается в разделе «условия применения системы»?

6) Какая
информация содержится в разделе «Описание операций»?

Руководство пользователя – это основной документ в составе эксплуатационной документации на автоматизированную систему (ГОСТ 34). Очевидно ли это?

Назначение руководства пользователя

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

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

Конкретный подход к написанию определяется многими факторами:

– назначением программы и областью ее применения;

– сложностью программы;

– количеством разнообразных вариантов использования.

Принимая во внимание все различия и особенности, сложно привести структуру любого Руководства пользователя к одному виду. Тем не менее, РД 50-34.698 предлагает нам такой список разделов:

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

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

– Подготовка к работе, где описывают комплектность дистрибутива, порядок установки и загрузки программы, а также способ проверки ее работоспособности;

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

– Аварийные ситуации, где описывают действия в нештатных ситуациях – сбоях в программе, ошибок в данных и т.д.;

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

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

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

Наличие Руководства пользователя регламентируется ГОСТ 34.201, а структура и содержание – РД 50-34.698. Однако, в зависимости от сложности, назначения и области применения ПО, различные Руководства пользователя могут отличаться друг от друга по способу, методике и стилю изложения.

Заключение

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

---

– разработка руководства администратора;
– создание руководства программиста;
– разработка руководства оператора.

---

Существует множество видов предоставления справочной информации пользователю – это и 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:

1. Click the Create button on toolbar.
2. On the Create Project overlay fill in all mandatory fields.
3. 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. Поддержка

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

Заключение

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

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

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

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

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

Простое пошаговое руководство

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

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

Так как же начать, зачем начинать, зачем вообще нужно руководство пользователя (да…)? Я постараюсь ответить на некоторые распространенные вопросы о создании руководства пользователя, а также помочь вам в создании вашего первого руководства пользователя в Docsie, но вы можете использовать любой другой инструмент…

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

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

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

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

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

Создание хороших руководств пользователя экономит время:

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

Обучение клиентов использованию ваших продуктов:

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

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

![] (https://cdn.docsie.io/workspace_tovPs7rKnzB4cmaiR/doc_ULxUK3nJlSUujhpeo/file_jripxf4mYymO4f3xy/boo_occBcYZBFuyefSBLr/fe45270c-c55d-dab5-f45c-363cc455ecb821.png)

Итак, чтобы начать создавать руководство пользователя, необходимо понять, какую проблему вы пытаетесь решить для конкретного клиента. Создание руководства пользователя для всего обо всем превращает его в непонятную кашу, которую не поймет никто, включая целевую аудиторию. Если вы посмотрите на некоторые из лучших примеров руководств пользователя в Интернете, написанных такими компаниями-суперзвездами, как Stripe или Slack. Вы заметите определенную закономерность.

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

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

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

Так что же входит в отличное руководство пользователя?

Давайте рассмотрим приведенное выше руководство по управлению книгой и определим несколько пунктов

Организация руководств пользователя

Использование Docsie для создания руководств пользователя

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

Коллекции используются для выделения различных книг, которые вы хотите показать разным типам клиентов. Например, эта коллекция используется для показа только бизнес-пользователям. Это означает, что мы выбрали только 3 книги из всех книг, созданных для показа этим конкретным клиентам.

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

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

Теперь давайте приступим к написанию первого руководства пользователя с помощью Docsie, это делается с помощью Docsies «Book».

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

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

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

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

![] (https://cdn.docsie.io/workspace_tovPs7rKnzB4cmaiR/doc_ULxUK3nJlSUujhpeo/file_w2Fo0BuxXtGjFQuzx/boo_occBcYZBFuyefSBLr/42e5df8b-db8e-ec6a-6a70-dc0420c427376.png)

Чтобы создать подразделы в руководстве пользователя, которые будут отображаться как 1.1, 1.2…ext, все, что вам нужно сделать, это выбрать местоположение текста и установить текст как «Заголовок», что делается нажатием на H во вкладке редактора.

![] (https://cdn.docsie.io/workspace_tovPs7rKnzB4cmaiR/doc_ULxUK3nJlSUujhpeo/file_OCwuils7ezubiAv8a/boo_occBcYZBFuyefSBLr/1dd88460-f856-79c7-96a9-e43c31fd5f217.png)

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

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

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

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

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

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

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