Блог технического писателя Ильи Жукова

Справка, Помощь, Help, F1

Установив на компьютер новую программу, мы чаще всего начинаем осваивать ее методом тыка. Если пользовательский интерфейс программы интуитивно понятен, это быстро приносит результат. Если разобраться с наскока не получилось, а программа очень нужна, мы ищем в Интернет видеоуроки, инструкции, описания в блогах. Иногда смотрим, есть ли документация на сайте разработчика или нажимаем на клавиатуре F1, чтобы открыть справку или помощь. Что же такое справка и почему ее также называют помощью? Для чего она нужна? Какая она бывает, и какая она должна быть? Давайте разберёмся.

Для чего нужна справка

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

символ справки или помощи

Что такое справка

Приведем несколько определений. «Документацией пользователя программного продукта называется полный комплект документов, поставляемых в печатном или другом виде, который обеспечивает целевое применение продукта пользователем, а также является неотъемлемой частью этого продукта» (Кагарлицкий 2012: 32).

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

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

Где могут храниться файлы справки

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

  • Локальная справка в прямом смысле встроена в программный продукт. Она, как правило, входит в дистрибутив и устанавливается в одну папку с программой. Иногда справку можно дополнительно загрузить из Интернет во время установки.
  • Удаленная справка обычно расположена на сайте компании-разработчика. Чаще всего это справка в формате WebHelp. При вызове из программного продукта такая справка открывается в браузере, используемом по умолчанию.
  • Комбинированная справка сочетает локальные и сетевые ресурсы. Часть справки хранится на локальном компьютере, а часть – подгружается из сети Интернет при обращении к соответствующим разделам (например, справка в Windows XP).

Платформы и форматы справки

Считается, что справка должна быть в любом приличном приложении. Для программ, работающих под управлением ОС Windows, стандартом справки является формат CHM (HTML Help). В Linux, iOS и Android — это может быть WebHelp или PDF. Если в приложении нет справки, есть смысл задуматься о его надежности. Ведь компания-разработчик могла сэкономить не только на справке!

Минимальный функционал справки

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

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

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

Какой должна быть хорошая справка

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

Мне ближе критерии качества, сформулированные сторонниками топик-ориентированного подхода (от англ. topic-based writing; IBM Style Guide 2011: 115) или тематического принципа (Кагарлицкий 2012: 89). Приведу основные требования к качеству справки (Developing Quality Technical Information 2004: 3).

Простота использования (easy to use):

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

Простота изложения (easy to understand):

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

Простота поиска (easy to find):

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

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

Какой справка не должна быть

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

 

Вместо заключения приведу немного статистики, которая может быть интересна не только техническим писателям, но и заказчикам разработки ПО, инвесторам. По данным Лаборатории Касперского (доклад Большаковой М., Соболевской М. 2017), эффективность размещенной на сайте базы знаний по продуктам компании в 2017 году составила порядка 80%. Это доля вопросов, решенных в базе знаний, по отношению к общему числу решенных вопросов. 20% пришлось на звонки в службу поддержки и письменные вопросы. Иными словами, если убрать с сайта базу знаний, нагрузка на службу поддержки возрастет примерно в 5 раз. Таким образом, качественная пользовательская документация и справка на практике экономят значительные ресурсы и могут быть эффективными.

 

Источники и дополнительная информация

The IBM Style Guide: Conventions for Writers and Editors (IBM-Press), 2011.

Developing Quality Technical Information: A Handbook for Writers and Editors (IBM Press), 2nd Edition, 2004.

Кагарлицкий Ю.В. Разработка документации пользователя программного продукта. Методика и стиль изложения. М., 2012.

Большакова М., Соболевская М. Битва за эффективность: полируем контент для пользователя. Лаборатория Касперского. Доклад, Пятый Гипербатон, 03 июля 2017 г.

Википедия. Документация на программное обеспечение.

 

Добавить комментарий

Последние статьи

Что нового в Help+Manual 8

10 февраля 2020 года вышла 8-я версия Help+Manual. Любой желающий может бесплатно скачать пробную версию с сайта компании-разработчика и оценить ее потенциал. В течени...

Читать полностью...

Работа со стилями в Help and Manual 7

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

Читать полностью...

Форматы справки для ОС Linux

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

Читать полностью...

Сборка CHM-файла в Help and Manual

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

Читать полностью...

Основные настройки проекта в Help and Ma…

Если для сборки справки не используется шаблон (skin-file), внешний вид и основной функционал CHM-справки берется из настроек проекта. В этой статье я расскажу о том, ...

Читать полностью...

Импорт CHM в Help and Manual

Программный комплекс Help and Manual позволяет импортировать документацию из ряда форматов, в том числе, из HTML и CHM. Готовую документацию можно загрузить как в суще...

Читать полностью...

Как отредактировать CHM в Help and Manua…

Если вам нужно внести несколько небольших правок в CHM-файл, такую задачу можно успешно решить при помощи бесплатных программ HTML Help Workshop и Notepad++. Серьезная...

Читать полностью...

Как сделать качественные скриншоты

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

Читать полностью...

Внесение изменений и сборка нового CHM-ф…

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

Читать полностью...

Создание и настройка проекта в HTML Help…

Установив необходимые бесплатные программы, мы разобрали исходный файл api.chm и получили 64 файла (подробнее смотрите материал Декомпиляция CHM-файла). Это основная ч...

Читать полностью...

Декомпиляция CHM-файла

Файл в формате CHM представляет собой скомпилированный HTML. В него могут входить HTML-страницы, рисунки, таблицы стилей, скрипты и другие файлы. Подробное описание со...

Читать полностью...

Редактирование CHM бесплатными программа…

Если заказчику или работодателю не принципиально, какое программное обеспечение использовать, я предпочитаю редактировать CHM в Help+Manual 7. Но как показывает практи...

Читать полностью...

Как отредактировать CHM-файл

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

Читать полностью...

Как создать справку в формате CHM

Формат HTML Help или CHM был разработан компанией Microsoft в 1997 г. Сегодня CHM остается стандартом справки для приложений, работающих в ОС Windows. Средство для про...

Читать полностью...

Бесплатный локальный сервер HM2GO для We…

Одна из моих предыдущих статей была посвящена особенностям работы WebHelp на локальных компьютерах. Некоторые популярные браузеры, в том числе Google Chrome, Opera и Я...

Читать полностью...

Дата в полном формате с месяцем в родите…

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

Читать полностью...

Все о справке и документации для пользователей!

Следить за новыми статьями:

© Илья Жуков, 2019. Охраняется законом об авторском праве.