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

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

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

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

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

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

1. Введение.
2. Назначение и условия применения.
3. Подготовка к работе.
4. Описание операций.
5. Аварийные ситуации.
6. Рекомендации по освоению.

1. Введение

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

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

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

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

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

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

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

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

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

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

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

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

1. наименование;
2. условия, при соблюдении которых возможно выполнение операции;
3. подготовительные действия;
4. основные действия в требуемой последовательности;
5. заключительные действия;
6. ресурсы, расходуемые на операцию.

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

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

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

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

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

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

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

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

Содержание руководства по эксплуатации

Руководство или паспорт по эксплуатации разрабатывается, принимая за основу ГОСТ 2.601-2019, в котором описаны принципы разработки разной эксплуатационной документации технического оборудования.

Обычно руководство по эксплуатации состоит из следующих основных разделов:

• Описание технического устройства и функции;
• Назначение и эксплуатация;
• Обслуживание устройства;
• Ремонт устройства;
• Правила хранения, перевозки и утилизации.

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

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

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

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

Что касается технического оформления руководства по эксплуатации, информация об этом также прописана в ГОСТе 2.601-2019. В нём можно найти такие детали, как носитель документа, формат и качество бумаги, шрифт и размер, и многое другое.

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

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

• Требования к руководству по эксплуатации
• Важные правила
• Кому может потребоваться руководство по эксплуатации?
• Какими ГОСТ и законами регламентируется порядок оформления документа?
• Каким должно быть содержание руководства по эксплуатации?
• Что может быть дополнительно?
• Как правильно оформить?
• Стиль оформления

Требования к руководству по эксплуатации

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

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

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

Важные правила

Составление РЭ проводится в соответствии с определенными правилами:

• Цель документа – разъяснение. Потребитель с помощью него обеспечивается всей необходимой информацией по использованию продукции;
• Вся представленная информация должна соответствовать остальной технической документации;
• Руководство должно полноценно отражать принципы работы и эксплуатации данного изделия или продукции в целом;
• Вся информация не должна противоречить государственным стандартам и существующим техническим регламентам;
• Язык написания документа должен быть простым, понятным для всех, кто планирует эксплуатировать продукцию.

Кому может потребоваться руководство по эксплуатации?

Документ может быть необходим и быть полезен для:

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

Какими ГОСТ и законами регламентируется порядок оформления документа?

Порядок оформления РЭ определен рядом нормативно-правовых документов и рекомендаций стандартов ЕСКД:

• ГОСТ 2.610-2006 – отражены общая система и правила тех. документов;
• ГОСТ 2.105-95 – отражены правила по тексту технической документации;
• ГОСТ 2.601-95 – указаны требования по оформлению РЭ;
• Также существуют требования, которые регламентируются Таможенным союзом: ТР ТС 016/2011, ТР ТС 010/2011 и другие.
• Для узконаправленной продукции оформление руководства по эксплуатации может еще регламентироваться дополнительными нормативами, например, Правилами безопасности оборудования.

Каким должно быть содержание руководства по эксплуатации?

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

1. Вводная часть;
2. Оглавление;
3. Подробное описание продукта, устройства или механизма;
4. Комплектность;
5. Подробное описание и условия его использования;
6. Монтаж;
7. Сервисное обслуживание, ремонт – указание возможных неполадок и способы их устранения;
8. Применяемые к условию стандарты, требования и нормы безопасности;
9. Гарантии производителя;
10. Правила по хранению и транспортировке;
11. Правила утилизации;
12. Предметный указатель (глоссарий).

Что может быть дополнительно?

Дополнительно РЭ часто содержит:

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

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

Как правильно оформить?

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

Стиль оформления

Стиль оформления текста – деловой, нейтрально-формальный, без использования стилистические окрашенных слов, чтобы не отвлекать пользователей от сути документа. Важно не дублировать информацию, писать кратко и по сути. Последовательность данных должна походить на последовательность действий пользователя. Вежливые обороты («пожалуйста») не используются, только повелительное наклонение («возьмите», «соберите» и т.д.). Информация должна быть максимально структурирована, с использованием списков и нумерации. Внешний вид документа тоже должен быть продуман. Это может быть корпоративный шаблон, цветовая схема или специально созданный дизайн. Восприятие красиво оформленного РЭ может быть спроецировано на изделие и повлиять на решение его закупки и использования.

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

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

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

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

 1. Стандарты

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

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

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

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

2. Структура

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Хорошо:
To create project:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

6. Поддержка

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

Заключение

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

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

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

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

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