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

Справка, Помощь, 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 г.

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

 

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

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

Создание CHM-справки в бесплатной програ…

KEL CHM Creator — это «новая» хорошо забытая программа, выпущенная в 2012 году, предназначенная для создания и декомпиляции CHM-файлов. Программа не требовательна к ре...

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

KEL CHM Creator — бесплатная программа д…

Если вам нужно создать CHM-файл, и вы больше не хотите пользоваться глючной программой HTML Help Workshop, тогда KEL CHM Creator — это ваш вариант. Программа позволяет...

Читать полностью...
ключевые слова

Ключевые слова в Help+Manual

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

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

HTML Help Workshop – бесплатная программ…

В 1997 году Microsoft выпустила новый формат справки, HTML Help (CHM), а также бесплатную программу для создания и редактирования справки в этом формате — HTML Help Wo...

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

HelpNDoc — бесплатная альтернатива Help+…

Еще одной альтернативой RoboHelp и Help&Manual является программа HelpNDoc от французского разработчика, компании IBE Software. Это практически полный аналог HelpS...

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

HelpSmith — достойная альтернатива Help+…

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

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

Dr.Explain — отечественная программа для…

За почти 30-летнюю историю существования RoboHelp и Help&Manual стали стандартом средств разработки справки и пользовательской документации в среде Windows. Сегодн...

Читать полностью...
вычитка текста

Как вычитать свой текст: инструкция для …

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

Читать полностью...
качество текста

Как повысить качество текста инструкций

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

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

Закон построения нехудожественного текст…

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

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

Примечания и предупреждения в тексте инс…

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

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

Методика чтения научных книг

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

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

Книга «Пиши, сокращай: как создавать сил…

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

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

Как починить поиск в русском PDF

Начинающий пользователь Help+Manual, пишущий документацию на русском языке, рано или поздно сталкивается с ситуацией, когда в созданном PDF-документе не работает поиск...

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

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

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

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

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

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

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

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

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

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