Виды руководства оператора - Arganabio.ru - инструкции по эксплуатации и многое другое

Практическая работа №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 «Руководство оператора. Требования к содержанию и оформлению». Ниже для
сравнения приведены структуры документа согласно двум перечисленным стандартам.

РД 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. Однако, в зависимости от сложности, назначения и области применения ПО, различные Руководства пользователя могут отличаться друг от друга по способу, методике и стилю изложения.

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

Наименование документа	Наименование стандарта	Стоимость разработки
РП на автоматизированную систему	РД 50-34.698	70 тыс. р.

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

Возможно, вас также заинтересует:

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

Туториал для туториалов. Как написать пользовательскую документацию

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

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

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

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

Пользователи бывают разные. То есть они могут отличаться как по возрасту, отрасли и опыту, так и по количеству мотивации. Мотивация особенно касается b2b сервисов. Многие пользователи попадают в продукты, потому что «Начальник сказал».
Продукты бывают сложные. Быстро разобраться и понять все их фишки без документации сложно или невозможно.

Документация помогает пользователю решить проблему или помочь разобраться с особенностями и фишками продукта. В любой документации люблю раздел Tips&Tricks.

Что входит в пользовательскую документацию

Пользовательская документация — это не юридические документы. У них другие цели.

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

Что еще можно отнести к пользовательской документации

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

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

Ответы на часто задаваемые вопросы (FAQ).
Руководство пользователя. Это самый жирный кусок из всей пользовательской документации. Здесь описывается весь интерфейс, только текстом.
Краткое руководство пользователя. Короткая презентация или документ для быстрого начала. Описывает базовые функции, возможности и советы для начала. Главное отличие от полного руководства — быстрее читаются, дают базовое представление о продукте и особенно помогают при внедрении b2b продуктов.
Описание отдельных фишек (Tips&Tricks). Чаще всего их делают в формате видеоуроков, но можно наткнуться и на текстовые.
Релизноуты. Считаю их важной частью пользовательской документации. И, говоря релизноуты, я имею ввиду не разовые, которые выкладываются в магазины приложений или к себе на сайт. А написанные раз в какой-то период. Можно раз в месяц. При работе над прошлым продуктом мы писали всё, что исправили или добавили за месяц. Хорошим тоном, на мой взгляд, будет писать самое важное.
Видеоуроки. Считаю их частью пользовательской документации, но это скорее вкусовщина, чем правило.

Почему это важно?

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

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

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

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

Красоты B2B рынка

Прошлый продукт, над которым мы с командой работали, умел и в облако, и в on-premise.
С облаком все понятно. Динамическая документация на сайте или в другом сервисе. Документация для корпоративных заказчиков имеет определенные особенности.

Особенность #1: Корпорации любят печатную документацию. Очень сильно.
Мой знакомый сейлз любит рассказывать истории про это.

Резюме его историй:

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

Поэтому чем толще кипа бумаги — тем лучше.

Особенность #2: Нужно отдавать дополнительные пакеты документов.
В дополнительные пакеты документов входит: документация по установке вашего ПО и документацию по его администрированию, а может ещё что-то, если попросят.

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

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

Где делать?

Много думал, долго смотрел. Переделывал наш гайд раз пять.

Когда искал, ставил для себя следующие задачи:

Документацию можно сделать динамической. То есть возможность грузить видео, гифки, делать кросс-ссылки.
Поддерживается базовое форматирование: заголовки, жирный, курсив, code, code block.
Возможность экспортировать в .pdf.

Небольшой совет

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

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

Какие вариант рассматривал:

Самописные.
Стоимость: может быть любой и измеряться в человеко-часах.
Плюсы: можно накрутить и наворотить, что по кайфу.
Минусы: долго, дорого, больно, потому что полноценный отдельный продукт, но для компаний больше 100 человек, может быть хорошим решением.
Google Docs.
Стоимость: Free
Плюсы: очень удобно работать с вёрсткой документа; привычный, при этом более простой интерфейс, относительно MS Docs; есть синхронизация с облаком; есть экспорт в .pdf.
Минусы: очень тяжело работать с визуальной частью — скринами; отношу в категорию не динамичных, так как выложить ссылочку на сайт на Google Doc конечно можно, особенно учитывая их последние апдейты, но это выглядит как-то не серьезно.
Notion.
Стоимость: можно Free, если работает один человек, а так от 8-10$ за человека.
Плюсы: очень удобно делать динамическую документацию, которую не стыдно выложить на сайт, по моим ощущениям; удобно работать в паре, есть все необходимое; можно вставить любое медиа, хоть ссылку, хоть видео, хоть схему из miro.
Минусы: не самый широкий спектр инструментов для работы с версткой; если неправильно сверстать, скопировать кусочек текста в другое место бывает накладно; не для всех пользователей привычная навигация по страницам.
Другие инструменты для wiki. Я смотрел на несколько вариантов wiki.js, Stonly 2, Dropbox Paper, Outline.

Смотрел давно, поэтому ничего вразумительно сказать не смогу. Помню, только что из всего выше, зацепил Dropbox и Wiki.js. В процессе написания этой статьи наткнулся ещё на один интересный сервис — GitBook. Он удовлетворяет всем моим запросам к подобным инструментам, но прошел мимо меня когда выбирал.
Figma.
Не пробовал, но хочу попробовать для ускорения работы именно с корпоративной документацией, есть у меня одна идея, как будет время попробую и расскажу.

С чего начать?

Не скажу ничего нового.
Начинать нужно с ответа на вопрос «Зачем мы это будем делать?». Мы начинали писать первую версию как раз для корпоративного заказчика. Но эта итерация была небольшой. Писали краткий гайд.

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

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

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

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

Основные правила

Понятный и простой язык

Я не буду писать о важности соблюдения правил русского языка: орфографии, пунктуации. И не буду рассказывать «Как писать хорошо?». Я сам далеко не эксперт в этом вопросе, поэтому когда мне нужно написать хороший текст я всегда обращаюсь к заветам Ильяхова и сервисам Главред, Яндекс.Спеллер и LanguageTools.

Любой текст должен быть простым и понятным.

Самое главное всегда это помнить.

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

Понятное и аккуратное форматирование

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

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

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

Основные кавычки оформляются елочкой «», внутренние кавычки оформляются лапками „“. Например, «Нажмите на вкладку „Контакты“ в левом верхнем углу», забугорные кавычки выглядят так «_».

Рекомендации по оформлению текста от Риановости
P.S. Иностранные названия в русском тексте кавычками не выделяются.
Тире и дефис.
Все знают про тире и дефис. Оказалось, что многие не знают про среднее тире.

Дефис (-) используется для присоединения частиц (что-то), для присоединения префиксов (по-братски), в словосочетаниях и сложносоставных словах (бизнес-ланч).
Среднее тире (–) применяется в числовом обозначении диапазонов и интервалов: 2011–2022, 11–12 ноября.
Длинное тире (—) используется для выделения прямой речи, указания маршрутов (Москва — Санкт-Петербург), между подлежащим и сказуемым.

Рекомендации по оформлению текста от Риановости

Оформление списков.
Существуют два вида списков: нумерованный и маркированный.

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

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

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

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

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

Если есть числа, то их нужно тоже оформить правильно. Не 2221, а 2 221. Отделяйте тысячные, это очень сильно упрощает восприятие.
Вы или вы.
Мое стойкое мнение — если это не коммуникация с кем-то из государственной организации в переписке, всегда писать вы и ваш с маленькой буквы. Иначе выглядит, что вы кричите на пользователя, а на пользователя нельзя кричать.

В случае с гос. организациями все очень просто, я считаю, что если они узнают, что можно писать с маленькой, их мир рухнет.
Буква Ё.
С этой буквой у меня особые отношения. Исторически моя фамилия пишется через Ё, но из-за передергивания правил русского языка в советском союзе моя фамилия теперь пишется через Е. Поэтому я долгое время принципиально везде писал Е. Годы идут. Мозгов прибавилось. Теперь стараюсь писать Ё везде, где ей место. Так действительно проще воспринимать текст.
Эмодзи в тексте 🦄
По этому поводу много споров как у нас в команде, так и в кругах пишущих. Я придерживаюсь мнения, что эмодзи в тексте допустимы, но очень дозировано.

Я использовал эмодзи для визуального подчеркивания каких-то кнопок в интерфейсе.
Например: Нажмите на символ ⚙️ в правом верхнем углу.

Для поиска символов пользуюсь Glyphy.

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

Если ваш продукт международный

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

Удобная навигация

Нет единого мнения — как правильно. Если самопис, я рекомендую делать вертикальную навигацию слева. Такая часто встречается в технических документациях.

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

Блок общего и важного.
- Описание вашего решения. Вдруг пользователь попал сначала на ваш гайд, а не на сайт.
- FAQ.
- Какие есть приложения, со ссылками на скачивания или как пользоваться, если это например веб-версия.
- Наши обновления.
Блок «Как начать». Сюда писать общие вещи, которые касаются всего сервиса. Особенно важный блок, если у вас мультиплатформенное решение.
Блок с руководством пользователя. Если у вас мультиплатформенное решение, то на каждую платформу лучше писать свое руководство. Можно объединять мобильные приложения и ПК версию. Так можно делать если нет глобальной разницы.

У нас, например, исторически разницы не было. Поэтому iOS и Android лежат на странице «Мобильные приложения». Но сейчас мы начали разделять, поэтому в будущем будет разделение на ОС.

Связность

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

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

Удобный поиск

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

Вот как мы это в Notion решили.

Логичность

Всё, что вы пишите должно быть логичным.

Порядок элементов в тексте и интерфейсе должен быть одинаковым. Пользователь ломается, когда написано: «Нажмите на вторую вкладку „Контакты“», а вторая вкладка — «Чаты».
Или когда в интерфейсе элемент называется «Назначить админом», а написано «Назначить администратором».

Понятная визуалка

Этот пункт я бы хотел разбить на два блока: работа с медиа и работа с Step-by-Step.

Работа с медиа

Я сторонник динамичных гайдов. Когда есть .gif или видео презентация. Это помогает увидеть наглядно. Если есть возможность, наполняйте вашу документацию .gif.
С видео все сложнее. Оно требует дополнительного действия от пользователя — включить, плюс весит больше чем .gif. Поэтому видео использую редко. Чаще для каких-то больших блоков или полноценных видеоуроков.

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

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

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

Из хороших приемов — блюрить лишнюю часть интерфейса или делать выделение лупой важной части.

Для работы со скриншотами я использую стандартный маковский редактор картинок, иногда Figma.

Step-by-step

Step-by-Step — это пошаговое описание всех действий, которые нужно выполнить пользователю, чтобы получить результат.

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

Делать нумерованные списки. Если есть подпункты, то нумеровать их соответственно и делать сдвиг вправо 1.1, 1.2, 1.2.1 и тд.
Писать сначала «Что нажать», потом «Где нажать». Исхожу из простой логики — сначала нужно понять «Что искать» и только потом «Где искать».

Например: «Нажмите на кнопку „Включить“ в правом верхнем углу», а не «В правом верхнем углу нажмите на кнопку „Включить“».
Вставлять визуальные элементы для кнопок, особенно если они без подписи. Для этой истории приходится немного костылить, если делать это в том же Notion, но в Google Docs это делать проще. Использую стандартные эмодзи и сервис Glyphy.

Например: Нажмите на символ ⚙️ в правом верхнем углу.

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

Поддержка и послесловие

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

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

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

Раз в 3-6 месяцев заходить и перечитывать, лучше если это каждый раз будет делать новый человек. Это нужно делать по трем причинам:

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

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

3. Всегда есть что улучшить. Текст это такой же продукт.

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

p.s. Пользовательская документация с которой все началось. Скажу сразу, там очень много чего можно и нужно улучшить. Бэклог по апдейту документации уже перевалил за 30 задач. Постепенно обновляем.

p.s.s. буду благодарен за конструктивный фидбек в комментариях и ещё больше, если поделитесь вашим опытом.

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

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

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

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

1. Стандарты

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

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

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

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

2. Структура

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Хорошо:
To create project:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

6. Поддержка

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

Заключение

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

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

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

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

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

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

Журавлев Денис

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

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

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

Общие советы по созданию пользовательской документации

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

После этого важно подумать о том:

Где пользователь будет к нему обращаться: дома, на работе, в машине?
Как часто он будет его просматривать?
Насколько объективно сложен для понимания продукт?

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

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

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

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

В первом разделе желательно рассказать общую информацию о программе:

Для чего создан продукт.
Какие задачи он решает.
Какие основные выгоды от использования для клиента.

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

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

Ни одно руководство не обойдется без таких разделов как: «Частые вопросы» и «Устранение типовых проблем» В них разбираются вопросы и проблемы, с которыми часто сталкиваются пользователи. Для заполнения данного раздела вам скорее всего понадобятся уже готовые отзывы клиентов. Если у вас абсолютно новый продукт, вы можете предугадать проблемы ваших клиентов либо на первое время не включать данный пункт в ваше руководство.

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

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

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

Одним из популярных инструментов для создания качественного руководства является программа Dr. Explain (https://www.drexplain.ru), в которой уже есть готовые шаблоны руководств пользователя с готовой структурой разделов и в которой удобно обновлять документацию, как бы часто эти обновления не происходили.

Видео-обзор основных возможностей программы Dr.Explain

Удобной особенностью инструмента является возможность экспортировать один и тот же документ в форматы: HTML, CHM, PDF. Простой и понятный интерфейс сам подскажет, как быстро просмотреть документ в различных форматах и настроить его под вывод в эти форматы.

Любой проект в Dr.Explain вы можете создать с нуля или импортировать уже существующую документацию, например из формата MS Word, HTML или CHM-файла, и буквально за несколько минут создать из нее онлайн-помощь, файл справки в формате CHM, или документ в формате PDF.

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

У программы свой собственный редактор, оптимизированный под работу со сложной документацией. Основные функции редактора вынесены в компактный тулбар. Это — управление стилем текста, форматирование абзацев, вставка ссылок, изображений, видео, таблиц и списков, а также вставка специальных объектов. Dr. Explain экономит время и силы своих пользователей. Разработчики документации часто сталкиваются с проблемой многократного использования одного и того же фрагмента текста и прибегают к очевидным решениям — «Ctrl+c», Ctrl+v». Dr.Explain предлагает решение по повторному использованию контента — текстовые переменные. Это решение экономит время, когда нужно много раз использовать один и тот же текст, особенно, который может периодически изменяться — например, версия документируемой системы.

Многие российские компании сталкиваются с тем, что руководство пользователя нужно писать согласно ГОСТ 19 и ГОСТ 34. Dr.Explain активирует поддержку требований ГОСТ фактически одним кликом. Программа автоматически сформирует структуру обязательных разделов и установит требуемые параметры страницы, стили абзацев, списков и заголовков.

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

Кроме того, Dr.Explain позволяет нескольким авторам одновременно работать над проектом с использованием сервиса www.tiwri.com, учетную запись на котором можно создать бесплатно за пару минут. При внесении правок одним автором сервис блокирует редактируемые разделы проекта для изменения другими авторами. По окончании редактирования изменения отправляются на сервер, и блокировка снимается. Так несколько человек могут одновременно работать над различными разделами проекта без риска помешать друг другу.

Попробовать режим многопользовательской работы в Dr.Explain можно даже с бесплатной лицензией. Вы можете создать общий проект и полноценно работать с ним в многопользовательском режиме до семи дней.

Почему компании выбирают Dr.Explain для создания руководств пользователя

Павел Свиридов, профессиональный военный, полковник, создатель астрологической системы «Вега Матрица»

«Только программа Dr.Explain обладала всеми необходимыми возможностями. А главное — она давала простор для творчества. Можно было выбрать цветовую гамму, вид и форму служебных элементов, настраиваемые шаблоны. Это позволило мне сохранить стилевое единство документации и самой программы. Ну, и конечно, полуавтоматическая обработка материала существенно облегчает и ускоряет работу по созданию хелпа.

Обучение работе в Dr.Explain было наглядным и сделано возможностями самой программы, что безусловно повлияло на мой выбор в ее пользу».

Прочитать полный кейс компании «Вега Матрица вы можете перейдя по ссылке

Наталья Обухова, бизнес-аналитик компании CRM Expert

«По классике жанра был пилотный проект на двух фаворитах (Dr.Explain и HelpNDoc) и муки выбора.

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

Сначала фаворитом выбора была другая система, но решающим фактором в пользу Dr.Explain стал возглас человека, выполняющего основную часть работы по переносу текста: «Вжух! И вся структура документа перенеслась в файл справки». Функция импорта в Dr.Explain отработала на ура и сэкономила кучу времени.

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

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

Прочитать полный кейс компании CRM Expert

Николай Вальковец, разработчик компании 2V

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

Прочитать кейс компании V2

Подытожим

Создание и написание хорошей пользовательской документации — это труд, который требует много времени и усилий. Но если успешно справиться с задачей, можно навсегда получить лояльных и довольных клиентов. Не забывайте о том, что недовольство от некачественного руководства может быть спроецировано пользователем на сам продукт и повлиять на дальнейшие решения о его выборе. Пользовательская документация должна стать персональным и незаменимым помощником. Используя Dr. Explain, вы сможете быстро создать качественное руководство пользователя, которое будет помогать пользователям разбираться в продукте, а вам позволит сосредоточить свои силы на более важных задачах — разработке и продвижении программного продукта.

Скачать Dr.Explain с неограниченной по срокам возможностью бесплатной работы можно по адресу: https://www.drexplain.ru/download/

Успешных вам разработок!

Смотрите также

Dr.Explain — инструмент для создания мобильной версии пользовательской документации к программным продуктам
Шаблоны файлов помощи, руководства пользователя программного обеспечения или сайта, шаблон базы знаний — бесплатные шаблоны и примеры пользовательской документации

From Wikipedia, the free encyclopedia

For a full guide to an item owned by its operator, see Owner’s manual.

A user guide, also commonly known as a user manual, is intended to assist users in using a particular product, service or application. It’s usually written by a technician, product developer, or a company’s customer service staff.

Most user guides contain both a written guide and associated images. In the case of computer applications, it is usual to include screenshots of the human-machine interface(s), and hardware manuals often include clear, simplified diagrams. The language used is matched to the intended audience, with jargon kept to a minimum or explained thoroughly.

Contents of a user manual[edit]

The sections of a user manual often include:

A cover page
A title page and copyright page
A preface, containing details of related documents and information on how to navigate the user guide
A contents page
A Purpose section. This should be an overview rather than detail the objective of the document
An Audience section to explicitly state who is the intended audience who is required to read, including optionals
A Scope section is crucial as it also serves as a disclaimer, stating what is out-of-scope as well as what is covered
A guide on how to use at least the main function of the system
A troubleshooting section detailing possible errors or problems that may occur, along with how to fix them
A FAQ (Frequently Asked Questions)
Where to find further help, and contact details
A glossary and, for larger documents, an index

History[edit]

The user guide engraved into a model of the Antikythera Mechanism.

User guides have been found with ancient devices. One example is the Antikythera Mechanism,^[1] a 2,000 year old Greek analogue computer that was found off the coast of the Greek island Antikythera in the year 1900. On the cover of this device are passages of text which describe the features and operation of the mechanism.

As the software industry was developing, the question of how to best document software programs was undecided. This was a unique problem for software developers, since users often became frustrated with current help documents.^[2] Some considerations for writing a user guide that developed at this time include:

the use of plain language^[2]
length and reading difficulty^[2]
the role of printed user guides for digital programs^[3]
user-centered design^[3]

Computer software manuals and guides[edit]

User manuals and user guides for most non-trivial software applications are book-like documents with contents similar to the above list. They may be distributed either in print or electronically. Some documents have a more fluid structure with many internal links. The Google Earth User Guide^[4] is an example of this format. The term guide is often applied to a document that addresses a specific aspect of a software product. Some usages are Installation Guide, Getting Started Guide, and various How to guides. An example is the Picasa Getting Started Guide.^[5]

In some business software applications, where groups of users have access to only a sub-set of the application’s full functionality, a user guide may be prepared for each group. An example of this approach is the Autodesk Topobase 2010 Help^[6] document, which contains separate Administrator Guides, User Guides, and a Developer’s Guide.

References[edit]

^ «Boffins decipher manual for 2,000-year-old Ancient Greek computer». Retrieved 2018-11-29.
^ ^a ^b ^c Chafin, Roy (January 1982). «User Manuals: What Does the User Really Need?». SIGDOC ’82 Proceedings of the 1st Annual International Conference on Systems Documentation: 36–39. doi:10.1145/800065.801307. S2CID 6435788.
^ ^a ^b McKee, John (August 1986). «Computer User Manuals in Print: Do They Have a Future?». ACM SIGDOC Asterisk Journal of Computer Documentation. 12 (2): 11–16. doi:10.1145/15505.15507. S2CID 35615987.
^ «Google Earth User Guide». 4 June 2009. Retrieved 13 August 2009.
^ «Getting Started with Picasa: Getting Started Guide». 15 June 2009. Retrieved 13 August 2009.
^ «Autodesk Topobase 2010 Help». Autodesk. Retrieved 13 August 2009.

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

Приятного чтения.

Если перед вами стоит вопрос – нужно ли вашему продукту пользовательское руководство, то отвечу сразу – да, нужно. Почему? На это есть две причины:

1. Качественная документация повышает лояльность клиента и ценность продукта в целом.

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

2. Руководство пользователя экономит время и силы техподдержки.

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

А теперь к советам!

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

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

— Где скорее всего пользователи будут прибегать к документации? (дома, на работе, в машине)

— Насколько объективно сложен для понимания продукт и как часто пользователь будет обращаться к документации?

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

(Для изложения лучше всего выбрать нейтрально-формальный стиль)

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

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

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

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

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

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

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

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

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

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

Представьте, что вы работаете в программе для создания пользовательской документации. Открываете меню основных настроек и видите раздел «аннотирование экрана» Заходите в него, там показаны разные стили аннотации, тени, фон и так далее. Но что такое аннотация? Допустим вы не знаете — нажимаете кнопку F1 и перед вами открывается руководство именно на той странице, где рассказано об «аннотировании экрана»

Как ее сделать? Смотрите ниже.

Контент

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

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

1. Понятность.

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

2. Наглядность.

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

3. Видео.

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

Но как добавить в документацию видео? Смотрите ниже.

Больше советов!

Когда документация будет готова, чтобы она стала «полноценной» её нужно опубликовать. Иначе какой от неё толк, если клиент не может её прочитать. У «юзера» всегда должен быть доступ к документации, и не важно где он. Такую потребность легко закрывают три формата: HTML, PDF и CHM.

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

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

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

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

Инструменты

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

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

Dr.Explain – программа для создания руководств пользователя для ПО, web-сервисов и баз знаний.

Благодаря «доктору» вы сможете опубликовать и обновлять документацию в востребованных форматах (CHM; HTML; PDF; DOC), не выходя из программы.

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

Импортируйте в программу заранее написанные фрагменты документации.

Вы сможете создать контекстно-зависимую документацию, настроить визуальный стиль руководства, добавить в него видео и многое другое!

Какой можно сделать вывод

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

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

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

Спасибо за внимание!

Со всеми возможностями Dr.Explain можно ознакомиться здесь:

Источник

В 2004 — 2005 годах был опубликован минимально необходимый набор «учебно-тренировочных» документов на программы, включающий техническое задание на программу по ГОСТ 19.201-78, программу и методику испытаний по ГОСТ 19.301-79, руководство оператора по ГОСТ 19.505-79. Этого достаточно для разработки программы, проведения испытаний и сдачи ее заказчику. Редакция от 23.01.2022.

Создан 16.02.2010 19:41:18

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

Структуру и оформление документа устанавливают в соответствии с ГОСТ 19.105-78.

Составление информационной части (аннотации и содержания) является обязательным [из 1.1 ГОСТ 19.505-79]

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

Состав руководства

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

назначение программы (1);
условия выполнения программы (2);
выполнение программы (3);
сообщения оператору (4).

В зависимости от особенностей документа допускается объединять отдельные разделы или вводить новые [из 1.2 ГОСТ 19.505-79]

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

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

В разделе «Назначение программы» должны быть указаны сведения о назначении программы (1.1) и информация, достаточная для понимания функций программы и ее эксплуатации (1.2) [из 2.1 ГОСТ 19.505-79]

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

Функциональное назначение

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

Эксплуатационное назначение

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

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

Состав функций

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

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

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

В разделе «Условия выполнения программы» должны быть указаны условия, необходимые для выполнения программы (2.1) (минимальный и (или) максимальный состав аппаратурных (2.2) и программных средств (2.3) и т.п.) [из 2.2 ГОСТ 19.505-79]

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

Климатические условия эксплуатации

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

Минимальный состав технических средств

В состав технических средств должен входить IBM-совместимый персональный компьютер (ПЭВМ), включающий в себя:

процессор Pentium-1000 с тактовой частотой, ГГц — 10, не менее;
материнскую плату с FSB, ГГц — 5, не менее;
оперативную память объемом, Тб — 10, не менее;
и так далее…

Минимальный состав программных средств

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

Требования к персоналу (пользователю)

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

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

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

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

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

Выполнение программы

В разделе «Выполнение программы» должна быть указана последовательность действий оператора, обеспечивающих загрузку (3.1), запуск (3.2), выполнение (3.3) и завершение программы (3.6), приведено описание функций, формата и возможных вариантов команд, с помощью которых оператор осуществляет загрузки и управляет выполнением программы (3.4), а также ответы программы на эти команды (3.5) [из 2.3 ГОСТ 19.505-79]

Автоматически, «пальцами», создаем подразделы:

Загрузка и запуск программы;
Выполнение программы;
Завершение работы программы.

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

Загрузка и запуск программы

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

В случае успешного запуска программы на рабочем столе будет отображено Главное окно программы.

Выполнение программы

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

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

Выполнение функции создания нового (безымянного) файла

Выполнение указанной функции возможно любым из перечисленных ниже способов:

последовательным выбором пунктов меню Файл-Создать;
нажатием кнопки .

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

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

Подход прост. Действие — результат, см. Схема «действие — результат» в совокупности с подходом «делай, как я сказал». Ошибочный результат – сообщение об ошибке.

Сторонники «дружественного» отношения к пользователю вправе озаглавить подраздел, к примеру, так — «Создание нового файла». Ни буква, ни дух ГОСТ 19.505-79 этому не препятствуют. В настоящем документе исключено прямое обращение к пользователю. Отсутствуют «откройте», «нажмите», «укажите» и пр. Применены штампы «следует открыть», «следует нажать» и им подобные (согласно ГОСТ 2.105-95).

Выполнение функции открытия (загрузки) существующего файла

Выполнение указанной функции возможно любым из перечисленных ниже способов:

последовательным выбором пунктов меню Файл-Открыть;
нажатием кнопки ;
последовательным нажатием клавиш Ctrl и O (сочетанием клавиш Ctrl+O).

В результате на рабочем столе будет отображено окно Открыть.

Примечание — Программа обеспечивает возможность загрузки файлов только с расширением *.rtf.

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

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

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

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

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

Редактирование текущего файла путем ввода текста с устройств ввода

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

пометку в тексте стартовой позиции редактирования;
ввод (набор) текста.

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

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

Редактирование текущего файла путем замены содержимого с применением устройств ввода

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

выделение текста, подлежащего замене;
ввод (набор) текста.

Для выделения текста, подлежащего замене, следует:

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

Фрагмент текста будет выделен цветом.

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

Редактирование текущего файла путем удаления содержимого с применением устройств ввода

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

выделение текста, подлежащего удалению;
удаление.

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

Удаление может быть выполнено любым из перечисленных ниже способов:

нажатием клавиши Delete;
нажатием сочетания клавиш Ctrl+X;
нажатием клавиши BackSpace.

Выполнение функции редактирования текущего файла с применением буфера обмена операционной системы

Указанная функция включает в себя перечисленные ниже операции:

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

Выполнение операции копирования (фрагмента) файла

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

выделение текста, подлежащего копированию;
копирование.

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

Выполнение указанной операции возможно любым из перечисленных ниже способов:

последовательным выбором пунктов меню Правка-Копировать;
нажатием кнопки ;
нажатием сочетания клавиш Ctrl+C.

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

Выполнение операции вставки содержимого буфера обмена в файл

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

пометку (указание) в тексте текущего файла стартовой позиции вставки;
вставку содержимого буфера обмена.

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

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

Выполнение указанной операции возможно любым из перечисленных ниже способов:

последовательным выбором пунктов меню Правка-Вставить;
нажатием кнопки ;
нажатием сочетания клавиш Ctrl+V.

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

Выполнение функции сохранения файла с исходным именем

Выполнение указанной функции возможно любым из перечисленных ниже способов:

последовательным выбором пунктов меню Файл-Сохранить;
нажатием кнопки ;
последовательным нажатием клавиш Ctrl и S (сочетанием клавиш Ctrl+S).

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

…

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

Завершение работы программы

Завершение работы программы обеспечиваются стандартными средствами операционной системы.

или

Выполнение указанной функции возможно любым из перечисленных ниже способов:

последовательным выбором пунктов меню Файл-Выход (см. рисунок такой-то);
нажатием кнопки .

Сообщения оператору

В разделе «Сообщения оператору» должны быть приведены тексты сообщений, выдаваемых в ходе выполнения программы (4.1), описание их содержания и соответствующие действия оператора (4.2) (действия оператора в случае сбоя (4.3), возможности повторного запуска программы (4.4) и т.п.) [из 2.5 ГОСТ 19.505-79]

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

«описание их содержания»

Ошибка сохранения файла

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

«и соответствующие действия оператора»

Для сохранения файла с именем уже существующего файла следует нажать кнопку Да.

Для сохранения файла с именем, отличным от имени существующего файла, следует:

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

Об иллюстрациях

Допускается содержание разделов иллюстрировать поясняющими примерами, таблицами, схемами, графиками [из 2.6 ГОСТ 19.505-79]

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

О приложениях

В приложения (5) к руководству оператора допускается включать различные материалы, которые нецелесообразно включать в разделы руководства [из 2.7 ГОСТ 19.505-79]

Все, что душе угодно.

Выводы

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

Причиной для таких утверждений, судя по всему, стали:

обычная лень — нежелание открыть ЕСПД и один-единственный раз (!) во всем разобраться;
тяга к оформительству, подогреваемая отдельными маститыми «техническими писателями»;
тяга к буржуйским стандартам (ибо нет пророка в своем отечестве);
и еще много чего.

Отдельно о буржуйских стандартах. Через некоторое время планируется опубликовать сравнительный анализ ГОСТ 19-й системы и IEEE Std 830-1998, а также IEEE Std 1063-2001 с целью показать:

превосходство советских стандартов 25-летней давности в целом;
«цельнотянутость» буржуйских с наших.

Примечание от 17.02.2010 г. — Сравнительный анализ указанных документов дан в статье «Как писать руководство пользователя? Часть I».

Источник

Руководство оператора – это основной документ в составе эксплуатационной документации на программное обеспечение (ГОСТ 19). Очевидно ли это?

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

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

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

Состав типового руководства оператора

Так, например, требования к содержанию и оформлению Руководства оператора представлены в ГОСТ 19.505. В соответствии с требованиями стандарта, документ должен содержать следующие разделы:

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

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

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

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

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

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

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

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

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

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

Стоимость разработки руководства оператора

Наименование документа	Наименование стандарта	Стоимость разработки
Руководство оператора на программное обеспечение	ГОСТ 19.505	70 тыс. р.

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

Возможно, вас также заинтересует:

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

Источник

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

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

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

Содержание

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

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

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

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

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

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

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

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

Стандарты

·
Комплекс
стандартов и руководящих документов на автоматизированные системы (ГОСТ 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 Руководство оператора
Введение
Область применения
Описание возможностей
Уровень подготовки пользователя
Перечень эксплуатационной документации, с которыми необходимо ознакомиться пользователю
Назначение и условия применения
Виды деятельности и функции, для автоматизации которых предназначена программа	Назначение программы
Условия, при которых обеспечивается применение программы	Условия выполнения программы
Подготовка к работе	Выполнение программы
Состав и содержание дистрибутивного носителя данных
Порядок загрузки данных и программ	Порядок загрузки, запуска и завершения программы
Проверка работоспособности
Описание операций	Описание функций
Описание всех выполняемых функций, задач, комплексов задач, процедур
Описание операций технологического процесса обработки данных, необходимых для выполнения функций, комплексов задач (задач), процедур
Аварийные ситуации (действия в случае длительных отказов технических средств, обнаружении несанкционированного вмешательства в данные, действия по восстановлению программ или данных, и т.п. )	Сообщения оператору
Рекомендации по освоению

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

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

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

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

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

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

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

Пример:

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

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

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

Пример:

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

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

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

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

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

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

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

1.
Введение.

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

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

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

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

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

1. Введение

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

15-30 секунд.

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

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

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

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

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

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

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

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

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

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

15 секунд.

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

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

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

Класс ошибки	Ошибка	Описание ошибки	Требуемые действия пользователя при возникновении ошибки
Портал ИАС КХД	Сервер не найден. Невозможно отобразить страницу	Возможны проблемы с сетью или с доступом к порталу ИАС КХД.	Для устранения проблем с сетью обратиться к сотруднику подразделения технической поддержки (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: Создание запросов
и отчетов

Ход
работы:

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

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

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

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

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

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

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

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

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

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

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

Источник

Общая информация

Документация принадлежит к типу программной, эксплуатационной документации пользователя. Объединяет в себе пакеты документов программы, программного компонента системы или комплекса. Создается для операторов. Целью документации является обеспечение оператору комфортной работы с программным продуктом. Все документы соответствуют стандартам: ГОСТ 19.505-79.

Предмет и применение

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

Содержание

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

Методология и язык написания

Язык текста должен быть максимально простым и понятным, инструкции – ясными и понятными.
1. Вся теоретическая информация сведена к минимуму и содержится в одном разделе.
2. Отсутствие ссылок.
3. Конкретные указания.
4. Описание производимых действий и их последствий.

Стандартная структура — согласно ГОСТ 19.505-79.

1. Назначение программы.
2. Условия выполнения программы.
3. Выполнение программы.
4. Сообщения оператору.

Источник

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

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

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

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

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

Возможно, вас также заинтересует:

Туториал для туториалов. Как написать пользовательскую документацию

Что входит в пользовательскую документацию

Почему это важно?

Красоты B2B рынка

Где делать?

С чего начать?

Основные правила

Понятный и простой язык

Понятное и аккуратное форматирование

Удобная навигация

Связность

Удобный поиск

Логичность

Понятная визуалка

Работа с медиа

Step-by-step

Поддержка и послесловие

1. Стандарты

2. Структура

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

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

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

6. Поддержка

Заключение

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

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

Общие советы по созданию пользовательской документации

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

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

Почему компании выбирают Dr.Explain для создания руководств пользователя

Подытожим

Смотрите также

Contents of a user manual[edit]

History[edit]

Computer software manuals and guides[edit]

See also[edit]

References[edit]

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

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

Контент

Инструменты

Какой можно сделать вывод

Состав руководства

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

Функциональное назначение

Эксплуатационное назначение

Состав функций

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

Климатические условия эксплуатации

Минимальный состав технических средств

Минимальный состав программных средств

Требования к персоналу (пользователю)

Выполнение программы

Загрузка и запуск программы

Выполнение программы

Выполнение функции создания нового (безымянного) файла

Выполнение функции открытия (загрузки) существующего файла

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

Редактирование текущего файла путем ввода текста с устройств ввода

Редактирование текущего файла путем замены содержимого с применением устройств ввода

Редактирование текущего файла путем удаления содержимого с применением устройств ввода

Выполнение функции редактирования текущего файла с применением буфера обмена операционной системы

Выполнение операции копирования (фрагмента) файла

Выполнение операции вставки содержимого буфера обмена в файл

Выполнение функции сохранения файла с исходным именем

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

Завершение работы программы

Сообщения оператору

Ошибка сохранения файла

Об иллюстрациях

О приложениях

Выводы

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

Состав типового руководства оператора