Как сделать справку для программы
Программа Dr.Explain для создания файлов справки и документации не требует опыта, подготовки или специальных знаний.
Dr.Explain поддерживает создание пользовательской документации из одного источника в различных форматах: HTML (online справка), CHM (файлы помощи для Windows-программ), MS Word, PDF.
Специальные знания не нужны! Создайте первый CHM help-файл за пару минут.
Создавайте и редактируйте разделы файла справки в удобном WYSIWYG редакторе.
Настройте оглавление, ключевые слова, меню и навигацию несколькими кликами.
Используйте Help ID для создания контекстной помощи.
Просто импортируйте старые файлы справки и продолжайте работать с ними в Dr.Explain. Добавьте в справку новые скриншоты, видео и эффекты.
Изменяйте дизайн и оформление файлов справки, используя предустановленные шаблоны.
Настраивайте заголовки, колонтитулы, раскладку.
Также создайте онлайн-справку или руководство пользователя по ГОСТ в формате PDF и DOC из того же проекта, без дополнительных усилий!
Импортируйте HLP, TXT, XML, HTML, или MS Word документы в Dr.Explain и создайте из них единый файл.
Дополнительные утилиты не нужны.
Единое оглавление и индекс для полнотекстового поиска будут созданы автоматически.
Добавьте свои логотип, скрипты, изображения, видео, корпоративные стили и копирайты в файл справки и сделайте его частью продукта.
Приведите в соответствие с требованиями ГОСТ 34 и 19 свою пользовательскую документацию.
Dr.Explain умеет анализировать пользовательский интерфейс приложений и создает скриншоты (копии экранов) окон, автоматически расставляя на них пояснительные выноски для элементов интерфейса.
Процесс сильно автоматизирован. Вы сможете быстро аннотировать экраны приложений и веб-сайтов для иллюстрирования пользовательской документации на ПО.
Статьи о создании и использовании CHM файлов справки в Dr.Explain для приложений на разных языках программирования
Для чего нужен CHM-файл справки
Как создать контекстную помощь из файла справки
Файлы справки в формате CHM являются самым подходящим средством для быстрого создания контекстной помощи для вашего Windows-приложения. Практически все современные языки программирования и среды разработки содержат встроенные методы для связи компонентов вашей программы с созданным файлом справки в формате CHM. Эти методы основываются на HtmlHelp API фирмы Microsoft, которое позволяет открывать конкретные разделы или выполнять поиск по конретной фразе в созданном файле справки прямо из вашего приложения.
Как создать справку в формате CHM
Формат HTML Help или CHM был разработан компанией Microsoft в 1997 г. Сегодня CHM остается стандартом справки для приложений, работающих в ОС Windows. Средство для просмотра CHM-файлов есть во всех версиях Windows 10. Более того, наличие справки в приложении часто рассматривается как один из показателей качества приложения. В этой статье я расскажу о том, как создать справку в формате CHM.
Справка в формате HTML Help (CHM) представляет собой скомпилированный HTML — автономный веб-сайт, сжатый и упакованный в файл формата CHM. Наряду со стандартным функционалом, таким как динамическое оглавление, указатель и полнотекстовый поиск, HTML Help может содержать и дополнительный функционал, например, избранное и т.д. Подробное описание формата можно посмотреть в статье Формат HTML Help. Создать CHM справку можно при помощи специальных программ, как платных, так и бесплатных.
Бесплатные программы для создания CHM-справки
MS HTML Help Workshop
Компания Microsoft, разработчик формата CHM, предоставила для создания справки бесплатный инструмент, HTML Help Workshop. Его можно свободно скачать с сайта компании по данной ссылке. В составе программы имеется максимально подробный файл справки на английском языке. На сайте есть подробное описание формата, также в оригинале.
Не буду приводить пошаговые инструкции по работе с данной программой. С 1997 года их прилично накопилось в сети Интернет. Ссылки на несколько описаний вы найдете в конце статьи. В печатном виде с пошаговыми инструкциями можно ознакомиться в книге А. Гультяева «Help. Разработка справочных систем» на страницах 187-208.
Очевидный, и, на мой взгляд, единственный плюс программы HTML Help Workshop — бесплатность. Создание более-менее серьезной справки в HTML Help Workshop — очень трудоемкая задача, выполнение которой растягивается на многие месяцы. При этом вы получите справку с базовыми возможностями формата CHM: текст, рисунки, ссылки. Регулярное обновление справки на базе проекта, созданного в HTML Help Workshop, практически нереально. Я пользуюсь данной программой исключительно для компиляции / декомпиляции CHM-файлов. В более продвинутых бесплатных и профессиональных программах, предназначенных для разработки справочных систем, HTML Help Workshop используется в качестве компилятора. Это говорит о солидном потенциале формата, скрывающемся под непростым пользовательским интерфейсом инструмента.
Рассмотрим еще несколько более продвинутых программ, при помощи которых можно создать справку в формате CHM: HelpNDoc и Help+Manual.
HelpNDoc
HelpNDoc — это условно-бесплатная программа от французского разработчика, компании IBE Software. Пользовательский интерфейс программы выполнен в стиле MS Office, поэтому работу с программой можно быстро и легко освоить. Для работы с текстом, рисунками, таблицами, ссылками и другим контентом в HelpNDoc используется простой и интуитивно понятный визуальный редактор. HelpNDoc работает по принципу единого источника и поддерживает экспорт проекта в ряд форматов справки, в том числе, CHM. Подробное описание программы на русском языке можно посмотреть здесь.
На момент написания статьи выпускается 3 редакции программы:
Существует множество пошаговых инструкций, как при помощи HelpNDoc создать справку в формате CHM. Они есть и в текстовом формате, и в формате видеоуроков на английском и на русском языках. Так, канал разработчика HelpNDoc на YOUTUBE содержит порядка 60 обучающих видео с пошаговыми инструкциями на английском языке. На русском языке можно рекомендовать работы Стремнева А.Ю., например, статью «Разработка электронных учебных пособий в системе HelpNDoc» (Высшее образование в России, №11, 2015 г.) и другие.
По опыту использования HelpNDoc в течение 2 лет могу поделиться только положительными впечатлениями. HelpNDoc позволяет быстро написать с нуля и оперативно обновлять справку в различных форматах. Во время работы с программой не хватает возможности вставки в документацию элементов, характерных для электронных форматов: раскрывающихся блоков с контентом (аккордеон), адаптивных изображений, размер которых автоматически подстраивается под размер окна и т.п. Разумеется, все это можно реализовать, используя готовые или написанные самостоятельно стили и скрипты, но это отрывает технического писателя от главной задачи: разработка и обновление справки.
Как создать профессиональную справку в формате CHM
Несмотря на то, что первой профессиональной программой для разработки справки, с которой я познакомился в 2003 году, был RoboHelp Х4 (в связке с RoboDemo 4 они использовались в проекте локализации библиотеки пользовательской документации, включая справку и электронный обучающий видеокурс), с 2005 года я предпочитаю работать с Help&Manual. Сегодня это программный комплекс Help+Manual 7, в котором, на мой взгляд, есть всё необходимое для автора пользовательской документации.
Help+Manual 7 Pro — это самый популярный программный комплекс для создания справки, пользовательской и различной технической документации. Он предназначен для разработки и локализации профессиональных справочных систем, руководств пользователя, баз знаний, электронных книг и другой документации в форматах CHM, WebHelp, PDF, DOCX, EPUB, MOBI и др. для настольных и мобильных приложений, iOS и Android, Windows и Linux.
Бесплатная книга по Help+Manual 7 Pro на русском языке
Большинство обучающих материалов и инструкций по Help&Manual написано на английском и немецком языках. Предлагаемая вашему вниманию книга на русском. В ней изложены основы работы с Help&Manual. Какая версия программного комплекса подходит для работы с кириллицей? Где взять Help&Manual? Как установить? Что и как настроить для начала работы? Ответы на эти и многие другие вопросы вы найдете в данной книге.
Даже если вы ни разу не делали справку в формате CHM, данная книга идеально подойдет вам. В ней подробно разбирается пользовательский интерфейс Help&Manual, настройки и порядок работы. Для всех этапов создания справки в формате CHM приводятся подробные пошаговые инструкции с рисунками. Изучив мою книгу, вы сможете самостоятельно:
Предварительный просмотр книги:
Чтобы бесплатно скачать книгу, пожалуйста, заполните форму:
Если есть вопросы по изложенному материалу или пожелания, что можно дополнительно включить в книгу, пишите в комментариях, либо воспользуйтесь формой обратной связи.
Введение
Установка Dr.Explain
Вы можете скачать установочный файл программы Dr.Explain на официальном сайте по адресу http://www.drexplain.ru/. Для этого воспользуйтесь кнопкой «Скачать бесплатно». После того как файл будет загружен запустите его. Для установки программы пройдите стандартную процедуру, следуя указаниям мастера (Рисунок 1). При использовании пробной версии Dr.Explain доступны все функции, но все изображения в экспортированных файлах помечаются водяными знаками.
Рисунок 1. Мастер установки «Dr.Explain»
Создание и настройка нового проекта
Рисунок 2. Окно «Проекты Dr.Explain»
Создание тематических разделов в файле справки
Рисунок 3. Дерево проекта «Dr.Explain»
Настройте порядок следования разделов в структуре документа с помощью пунктов «Выше» и «Ниже» контекстного меню. Изменить названия тем можно с помощью пункта «Переименовать».
Далее создайте содержимое разделов, выберите интересующий пункт в дереве проекта и приступайте к заполнению в окне редактора. Заполняйте раздел в свободной форме. В редакторе предусмотрены основные стандартные функции редактирования и форматирования текста и ряд функция для работы с изображениями, видео, таблицами и переменными. Использование переменных позволяет заменить повторяющиеся данные именем переменной. В таком случае при изменении присвоенного переменной значения, соответствующий текст изменится во всем документе.
Для повышения удобства поиска по файлу справки создайте и настройте ключевые слова. Откройте окно ключевых слов — кнопка «Ключевые слова» (Рисунок 4). Для добавления и удаления слов служат одноименные кнопки. Настройте привязку тем к словам, для этого выбрав интересующий раздел в структуре проекта, проставьте метки в полях тех терминов, которые хотите ассоциировать с данной темой.
Рисунок 4. Ключевые слова
Рисунок 5. Окно «Захват объекта»
Рисунок 6. Результат выполнения захвата объекта
Настройка значений Help ID
Рисунок 7. Изменение значения Help ID в окне «Свойства страницы»
Для проверки уникальности идентификаторов разделов используйте пункт «Инструменты –> Проверка проекта на ошибки» главного меню. Если в документе будут обнаружены повторяющиеся значения Help ID, в открывшемся окне появится сообщение с указанием повторяющихся значений. Устраните дублирования для правильной работы вызова разделов справки.
Предварительный просмотр и сохранение проекта
Перед экспортом проекта используйте функцию предварительного просмотра — кнопка «Просмотр CHM», чтобы убедиться в корректном отображении всех разделов справки. Если необходимо внести изменения, вернитесь в режим редактирования.
Экспорт проекта в CHM-файл
Рисунок 8. Окно «Экспорт в CHM»
Рисунок 9. Редактор форм среды разработки Microsoft Visual Studio
Рисунок 10. Редактор кода среды разработки Microsoft Visual Studio
При таком способе вызова файла справки при любых его перемещениях необходимо заново указывать в коде полный путь.
Будьте внимательны, для обеспечения правильной работы элемента вызова файла справки строго соблюдайте синтаксис, приведенный в примерах.
ОБРАТИТЕ ВНИМАНИЕ: Допускается использование нескольких компонентов «Help Provider». Это удобно в том случае, когда информация о различных элементах содержится в различных файлах справки. Также вы можете использовать отдельные компоненты для различных форм;
ОБРАТИТЕ ВНИМАНИЕ: Если файл справки располагается в одной папке с исполнительным файлом приложения, то достаточно указать только имя файла. При раздельного размещении файлов необходимо указать полный путь. В таком случае при любом перемещении файла справки, значение параметра «HelpNamespace» должно быть заменено актуальным.
ОБРАТИТЕ ВНИМАНИЕ: Количество параметров «HelpKeyword …» и «Help Provider…» в свойствах объектов соответствует количеству используемых компонентов «Help Provider», а цифра в наименовании параметра соответствует номеру компонента. Будьте внимательны при заполнении данных полей;
Открытие определенных разделов файла справки с помощью компонента Help Provider
Помимо вызова определенных разделов файла справки по соответствующим им HelpID, компонент «HelpProvider» также может быть использован для адресации разделов с использованием других параметров. Для настройки вызова определенных разделов необходимо установить соответствующие значения полей «HelpKeyword on Help Provider1» и «Help Navigator on Help Provider1» в свойствах элементов. Для настройки вывода определенных разделов файла справки при нажатии клавиши «F1» проделайте следующие действия:
·AssociateIndex— открывает вкладку «Указатель» иподсвечивает в списке первое по порядку ключевое слово, название которого начинается с сочетания символов в поле «HelpKeyword on Help Provider1»;
·Index — открывает вкладку «Указатель» и подсвечивает в спискеключевое слово, указанное в поле «HelpKeyword on Help Provider1»;
·Find — открывает вкладку «Поиск»;
·TableOfContents — открывает оглавление;
·Topic — открывает раздел, название которого указано в поле «HelpKeyword on Help Provider1».
ОБРАТИТЕ ВНИМАНИЕ: Название раздела указывается в формате «Topic.htm», это необходимо для правильной работы вызова справки.
·TopicId — открываетраздел,которому соответствует параметр Help ID, указанный в поле «HelpKeyword on Help Provider1»;
·KeywordIndex — открывает вкладку «Указатель» и выводит список разделов, содержащих ключевое слово, указанное в поле «HelpKeyword on Help Provider1».
Такой способ вызова справки позволяет гибко настроить адресацию и поиск в справочной системе, а также использовать для каждой отдельной формы или элемента соответствующий им файл справки или отдельные его разделы.
Если необходимо вызвать определенный раздел справочной системы с помощью кнопки, используйте следующие фрагменты кода:
Код вызова стартовой страницы справки:
где help.chm — имя файла справки (файл справки должен быть размещен в одной папке с исполнительным файлом приложения).
Код вызова вкладки «Указатель»:
Код вызова оглавления:
Код вызова вкладки «Поиск»:
Код вызова поиска по первым буквам ключевого слова:
где me — сочетание букв для поиска
Код вызова поиска по ключевому слову:
где FAQ — ключевое слово
Код вызова раздела по его названию:
где Overview.htm — название раздела (ключевое слово всегда указывается в формате Topic.htm)
Код вызова раздела по его HelpID:
где 1500 — значение HelpID интересующего раздела
Код вызова списка разделов, содержащих ключевое слово:
где menu — ключевое слово для поиска разделов.
Справка, Помощь, Help, F1
Установив на компьютер новую программу, мы чаще всего начинаем осваивать ее методом тыка. Если пользовательский интерфейс программы интуитивно понятен, это быстро приносит результат. Если разобраться с наскока не получилось, а программа очень нужна, мы ищем в Интернет видеоуроки, инструкции, описания в блогах. Иногда смотрим, есть ли документация на сайте разработчика или нажимаем на клавиатуре F1, чтобы открыть справку или помощь. Что же такое справка и почему ее также называют помощью? Для чего она нужна? Какая она бывает, и какая она должна быть? Давайте разберёмся.
Для чего нужна справка
Справка нужна для того, чтобы помочь нам разобраться, как использовать программу, как с ее помощью решить какую-либо задачу или проблему. То есть, справка — это, прежде всего, документация для пользователя. Символом справки чаще всего является знак вопроса или спасательный круг. Отсюда и варианты термина справка и помощь (от англ. help).
Что такое справка
Приведем несколько определений. «Документацией пользователя программного продукта называется полный комплект документов, поставляемых в печатном или другом виде, который обеспечивает целевое применение продукта пользователем, а также является неотъемлемой частью этого продукта» (Кагарлицкий 2012: 32).
Для справки можно предложить следующее определение: справка или помощь – это пользовательская документация в электронном формате, встроенная в программный продукт. Последнее утверждение не следует понимать всегда буквально. «Встроенная» значит: является неотъемлемой частью программного продукта, вызывается из данного программного продукта.
Справка или помощь поставляется в электронном виде. Она может состоять из одного или нескольких файлов, содержащих оглавление, текст, рисунки, или определяющих внешний вид и функционал справки (файлы скриптов, таблицы стилей, шрифты и т.д.). Поэтому в отношении справки часто используются термины справочная система (от англ. online help) и файлы справки (от англ. help files).
Где могут храниться файлы справки
По месту расположения файлов справка может быть локальной, удаленной, либо комбинированной:
Платформы и форматы справки
Считается, что справка должна быть в любом приличном приложении. Для программ, работающих под управлением ОС 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 раз. Таким образом, качественная пользовательская документация и справка на практике экономят значительные ресурсы и могут быть эффективными.
Источники и дополнительная информация