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

Итак, вы создали программное обеспечение, которое собираетесь продать и неплохо на этом заработать. Программа, скомпилирована, отлажена и протестирована. Единственное, чего ей не хватает, — это файла помощи. Ни одно серьезное программное обеспечение не обходится без модуля справочной информации и руководства пользователя. Это придает программе законченный вид и показывает заботу о пользователе. В этом обзоре будет рассмотрена программа Help&Manual от компании EC Software, способная генерировать help-файлы самых различных форматов.

Главным преимуществом программы является ее универсальность. С ее помощью можно получить файл справочной информации в любом из наиболее распространенных на сегодняшний день форматов (CHM, HLP, HXS, HTML, PDF, RTF, EXE, XML). Интуитивно понятный интерфейс делает программу простой в освоении. Основной блок программы составляет текстовый редактор, мало отличимый от MS Word как по интерфейсу, так и по количеству возможностей.

Интерфейс программы

Интерфейс состоит из двух областей. Первая – это панель Navigation с древовидной структурой содержания файла. Вторая – редактор страниц.

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

Редактор страниц состоит из трех закладок: Topic Options (опции), Page Editor (редактор страницы), XML Source Code (исходник в формате XML).

Картинка с сайта: www.ixbt.com

Главное окно программы

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

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

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

Рассмотрим некоторые важные инструменты редактора.

Якоря

Якорем в программе называется невидимая метка в тексте страницы, к которой будет осуществляться переход по ключевому слову или по гиперссылке. Добавляя якорь, мы указываем для него идентификатор и ключевые слова. Все ключевые слова, указанные как целиком для страниц, так и для якорей, будут выводиться на странице «Указатель (Предметный указатель, Index) сгенерированных файлов помощи». Щелкнув по выбранному ключевому слову, будет осуществлен переход к объекту, на который то ссылается: страницу или якорь.

Картинка с сайта: www.ixbt.com

Окно добавления якоря

Гиперссылки

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

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

  Картинка с сайта: www.ixbt.com

  Окно добавления гиперссылки

• Интернет-ссылки. В этом случае здесь указывается адрес страницы или электронной почты. Для первого варианта можно задать, в каком окне страница будет открываться: в том же или в новом (имеет значение только для файлов CHM, HTML и XML). Причем адрес должен быть полным (например, http://www.yandex.ru , а не www.yandex.ru). Для второго варианта будет создаваться электронное письмо с исходящим адресом, указанным в ссылке.
• Ссылки на файлы. Указывается файл, который будет открываться при переходе по ссылке.
• Ссылка на скрипт. Для этого случая в параметрах ссылки пишется выполняемый скрипт или макрос.

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

Условия

Если есть необходимость добавить в проект текстовый блок, который должен отображаться только в избранных форматах файлов помощи, то на помощь придет инструмент «Условие».

Окно добавления условия

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

Текстовые переменные

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

Окно добавления текстовой переменной

Комментарии

При написании помощи нередко ее автору требуется вставить на страницу текст, интересный только ему. Эту роль в программе выполняет инструмент «Комментарий». Он вставляет на страницу текстовый блок желтого цвета, который при компиляции файла игнорируется.

Свойства проекта

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

Картинка с сайта: www.ixbt.com

Окно параметров проекта

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

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

Следующие семь групп содержат индивидуальные настройки для каждого формата файла помощи. Например, параметры страницы для RTF или доступность текста для выделения и копирования в файле eBook(EXE).

Внешние компоненты

Из дополнительных средств Help&Manual хочется обратить внимание на три внешние компоненты, помогающие в написании инструкции.

Первая – это мощный фотограф скриншотов Screen Capture. Данная утилита позволяет делать снимка произвольной области экрана и даже отдельных элементов интерфейса: панелей инструментов, областей ввода и прочего. Более подробно, в качестве самостоятельного приложения, она описана в статье «Фотографируем окна».

Второй инструмент – это редактор шаблонов Print Manual Designer для будущих файлов в формате PDF. Здесь можно задать разметку страниц и с помощью текстовых переменных определить, как будет выводиться исходный текст в будущем файле. Шаблон, созданный в этом редакторе, сохраняется в файле MNL и в свойствах проекта подключается к настройкам формата PDF.

И последнее приложение, на которое следует обратить внимание, — это графический редактор Impict. Это довольно простой (но не примитивный) и удобный графический редактор, достаточный для нужд написания документации. Оперируя небольшим набором графических примитивов, данная утилита позволяет с легкостью создавать схемы, рисунки и диаграммы, а накладываемые эффекты позволяют сделать каждый объект изображения по-своему уникальным. Из объектов, создаваемых редактором, особо хочется выделить объект «Лупа», позволяющий увеличить изображение, на которое он накладывается. Этот инструмент будет очень полезен при работе со скриншотами с большим количеством мелких деталей.

Компиляция файла помощи

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

Картинка с сайта: www.ixbt.com

Окно компиляции

Удобной особенностью режима компиляции является возможность включения в скомпилированный файл опций файлов других форматов. Например, в исходном тексте у вас присутствуют условия, выводящие текстовые блоки только для файлов HLP. Но однажды вам понадобилось собрать файл в формате PDF и включить туда упомянутые текстовые блоки. Для этого вам не понадобится переписывать исходный текст проекта, достаточно в окне компиляции выбрать формат файла PDF и поставить галочку Classic Winhelp (.HLP). Cледует заметить, что для компиляции файлов CHM и HLP понадобятся собственные компиляторы. Если они не установлены в системе, их можно скачать здесь.

Резюме

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

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

Сам иногда занимаюсь help-файлами и не понаслышке знаю, что создание справочной системы занимает время и является кропотливой и нудной работой, особенно документирование интерфейса. Однако пару месяцев назад открыл для себя инструмент, который значительно ускоряет этот процесс. Речь идет о программе Dr.Explain от самарской компании Индиго Байт Системз. Она мне понравилась продуманным интерфейсом и возможностью документировать интерфейс ПО в полуавтоматическом режиме.

Dr.Explain vs. Help and Manual

Итак, Dr.Explain позволяет создавать help-файлы в формате CHM для поставки вместе с приложением, справочные системы в HTML для размещения на сайте продукта, а также руководства пользователя в RTF и в PDF с оглавлениями и ссылками. Справочная система генерируется в разных форматах из единого источника, что позволяет быстро обновлять документацию при выходе новых версий ПО. В этом плане Dr.Explain ничем не отличается от Help and Manual, которой я давно пользуюсь.

Интерфейс состоит из двух областей. Первая – это панель навигации с древовидной структурой содержания проекта. А вторая – редактор страниц.

В дереве задается вся структура help-файла, включая заголовки папок и страниц. Редактор страниц состоит из стандартных инструментов для написания и форматирования текста, а также имеются инструменты для вставки гиперссылок, картинок, таблиц и переменных. Все это есть и в Help and Manual, но панель инструментов в Dr.Explain скомпонована, на мой взгляд, более продуманно.

Сравним:

Рисунок 1. Панель инструментов Dr.Explain

Рисунок 2. Панель инструментов Help and Manual

Главная фишка Dr.Explain – это автоматизация самого трудоемкого процесса документирования – создание аннотаций пользовательского интерфейса. Да, вы правильно меня поняли. Больше не нужно делать снимки экрана самому, рисовать выноски и стрелки, вставлять все это хозяйство в проект вручную – программа сама сделает снимок любой части интерфейса по вашему выбору, проанализирует и найдет (сама!) все значимые элементы (кнопки, элементы управления, списки), вставит снимок в проект справки и автоматически расставит стрелки и пояснительные выноски к изображениям. Пользователю остается всего лишь ввести краткое пояснение к каждой выноске и все.

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

Такое полуавтоматическое документирование интерфейса значительно ускоряет и облегчает создание справочной системы, т.к. разработчику остается всего лишь добавить свои описания в выноски. В Help and Manual я все это тоже могу сделать – правда, придется делать это вручную. Обычно я делаю снимки окон в Snagit, обрабатываю края снимка, добавляю тень, рисую стрелки. А для документирования элементов окна вручную создаю табличку, нарезаю снимки кнопок и контролов, обрабатываю их края и вставляю в проект, а затем пишу описания каждой выноски. На это тратится уйма времени и усилий.

Кое-что еще…

В Dr.Explain есть и другие полезные возможности, которых, к сожалению, нет в Help and Manual. Например, есть удобный режим просмотра проекта – одним кликом по соответствующей кнопке можно быстро посмотреть, как будет выглядеть справка в формате CHM или HTML после компиляции. Превью открывается прямо в окне редактора. Поверьте, это очень удобно. Однако нет PDF-превью – это минус. В Help and Manual чтобы посмотреть, как выглядит справка, нужно постоянно компилировать проект.

Также в программе есть возможность интегрировать контекстно-зависимую справку прямо в приложение (F1), управление деревом навигации, набор шаблонов оформления, поддержка CSS, возможность быстрого обновления документации при выходе новой версии программы путем замены иллюстраций, но с сохранением выносок, аннотаций, описаний; функция поиска и индексации в онлайн-справке без программирования (PHP, ASP) или баз данных на стороне сервера.

Резюме

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