Справочная система малой кровью: Help & Manual 4

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

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

Здесь мы будем рассматривать только справку для платформы Windows, т.к. в мире Unix многие продукты десятилетиями обходятся без какого-либо Help'а, и вполне ничего себе живут. В мире Windows больше всего распространены форматы справки WinHelp и HTML Help.

Сначала взглянем, что нам предложит производитель самой платформы. Процесс создания справки, предлагаемый корпорацией Microsoft, как обычно, легкостью и изяществом не отличается. Если вы задумали делать справку в формате WinHelp, вам предстоит изрядно потрудиться в Word'е (или в WordPad'е, или в любом другом редакторе, поддерживающем формат RTF), расставляя сноски и атрибуты для специального управляющего текста. Для HTML Help "Мелкомягкие" предлагают простой текстовый редактор для разметки гипертекста. Впрочем, никто не запрещает воспользоваться FrontPage, Dreamweaver, GoLive, CoffeeCup HTML Editor или Netscape/Mozilla Composer. Но индекс тем как для WinHelp, так и для HTML Help, в любом случае придется составлять и связывать с текстом справки самостоятельно.

Поэтому нет ничего удивительного, что буквально спустя несколько месяцев после выхода Windows 95 появились первые программы, упрощающие создание справки к программным продуктам для платформы Win32. Но сейчас мы поговорим совсем даже не о них, а о новой версии лучшего средства для создания справки под "Окошки". Его название вы видите в заголовке статьи - это Help & Manual, версия - 4. Точнее, 4.1. Вышла эта версия совсем недавно и содержит в себе много очень хороших и полезных новшеств. Вы можете обнаружить ее на официальном сайте программы по адресу www.helpandmanual.com.

Мне кажется, впрочем, стоит все же рассказать не только о новых возможностях программы, но и вообще о Help & Manual, в целом. Хотя многие профессиональные разработчики, которые пишут документацию к программному обеспечению (не только программисты, но и технические писатели) пользуются этой замечательной программой уже давно, до сих пор на многих форумах нет-нет да и возникнет кто-нибудь с вопросом вроде: "Чем лучше справку делать?". Надеюсь, эта статья хоть немного уменьшит количество подобных вопросов.

Help & Manual - профессиональный редактор справки со встроенным WYSIWYG1-дизайнером. В отличие от многих других программ для создания электронной документации, Help & Manual не требует установленного Microsoft Word, а потому не вызовет нареканий у пользователей OpenOffice.org, Corel WordPerfect Office или Sun StarOffice. В то же время возможности встроенного редактора не сильно хуже "Вордовских": поддерживается вставка различных рисунков, видеоклипов, OLE-объектов, горизонтальных линий, ссылок и "якорей", таблиц. Причем, в отличие от MS Word, имеется возможность вставки специальных переменных, которые в процессе генерации справки заменяются на введенные пользователем в опциях проекта значения. Например, удобно использовать переменную <APPNAME> вместо самого названия продукта, если оно (название) еще окончательно не утверждено. Кроме того, в версии 4 появилась возможность вставлять "условный" текст. Этот текст попадает в генерируемый программой файл справки, только если на этапе компиляции выполняется какое-либо условие (например, вставка этого текста может зависеть от версии программы, для которой пишется справочная система, или выбранного формата справки).

В то же время проекты справки Help & Manual имеют собственный специальный формат, который может быть преобразован в WinHelp, HTML Help, HTML Help 2.0 (формат, используемый справкой Visual Studio, MSDN, Platform SDK, Delphi 2005/2006 и некоторыми другими приложениями), PDF (Adobe Acrobat), RTF (Rich Text Format, поддерживаемый Microsoft Word), HTML для показа справки в браузере, XML и eBook. Последний формат представляет собой исполняемый файл с включенным в него содержимым справки и движком просмотра HTML, независимым от Internet Explorer'а - фактически, аналог HTML Help. Стоит также отметить, что для создания справки в формате PDF совсем не обязательно иметь установленный Adobe Acrobat - программа умеет совершенно самостоятельно создавать файлы этого популярного формата. Специально для создания PDF-файлов в комплекте Help & Manual поставляется утилита Print Manual Designer, которая придаст справке в формате PDF вид, приближающий ее к печатному руководству по программе. Таким образом, вы можете использовать один и тот же редактор для разных форматов справки, и если вдруг придется переходить с одного из них на другой, то с Help & Manual этот процесс не вызовет особых трудностей.

С помощью Help & Manual можно редактировать и уже имеющуюся справку во всех форматах, поддерживаемых программой, кроме PDF и eBook. Удобный мастер импорта поможет практически без потерь декомпилировать имеющийся файл помощи и тут же приступить к его редактированию. Кроме форматов, описанных выше, Help & Manual 4 умеет импортировать проекты справки RoboHelp Office X5, Великого и Ужасного, о котором я вам тоже когда-нибудь расскажу.

Среди других удобств Help & Manual стоит отметить проверку орфографии (поддержку русского языка придется скачивать отдельно, белорусского же пока нет в помине). Редактор текста поддерживает Юникод (многобайтовую кодировку текста), т.е. можно без проблем вставлять символы национальных алфавитов, не опасаясь, что они начнут конфликтовать между собой. Кроме того, мастер синхронизации проектов позволит параллельно разрабатывать справочную систему для вашего продукта на нескольких разных языках. Редактор сам подсвечивает неработающие ссылки (т.е. те, которые ссылаются на несуществующую тему; URL он, конечно же, не проверяет). Кроме того, если навести курсор мыши на любую из ссылок (как на ссылку внутри проекта, так и на URL), редактор кода выведет подсказку с адресом.

По сравнению с версией 3, очень сильно улучшилось редактирование таблиц. Если в третьей версии Help & Manual вставка таблицы вызывала много проблем, то теперь ее редактирование практически не отличается от Word'овского, поддерживаются даже вложенные одна в другую таблицы.

В версии 4.1 появился редактор XML-кода справки, так что все желающие могут собственноручно отредактировать разметку текста справки. Вообще говоря, в версии 4.0 редактор уже работал с XML-разметкой текста, просто ее исходный код никто не видел. В версии 3.0 редактор был ориентирован на формат RTF, из-за чего и возникали проблемы с рисунками и таблицами. Но в четвертой версии разработчики заново написали редактор текста, из-за чего весь продукт очень сильно выиграл. Ручное редактирование XML-кода может пригодиться в особо сложных случаях, когда нужно точно подогнать параметры какого-либо объекта (таблицы, рисунка, видеоклипа и т.д.), а сам синтаксис XML-разметки Help & Manual подробно описан в справочной системе.

Говоря о Help & Manual, нельзя не сказать о дополнительных утилитах, входящих в комплект поставки этого замечательного средства. Об одной из них - Print Manual Designer - я уже вскользь упомянул, теперь расскажу об остальных. Screen Capture предназначена для создания снимков экрана (т.н. "скриншотов"), причем со своей задачей она справляется весьма профессионально. По ходу проведения "съемки" Screen Capture может увеличить или уменьшить изображение, добавить к нему тень или изменить яркость и интенсивность цветов. Получаемые изображения можно сохранить в GIF, PNG или BMP. Другая утилита, имя которой - Project Reports, позволяет автоматически создать отчет по проекту Help & Manual, причем можно и по каждой теме в отдельности. Отчет включает в себя различные статистические данные, а также найденные ошибки (отсутствующие картинки и видеоклипы, нарушенные ссылки); имеется пять стандартных видов отчетов. Эта возможность предусмотрена для того, чтобы руководители проектов могли проконтролировать и оценить труд создателей справочной системы. Следующая утилита - Image Editor, также имеет название Impict. Вот что пишут о ней сами разработчики: "Impict - не "рисовалка" вроде Adobe PhotoShop, Jasc PaintShop Pro или Ulead PhotoImpact. Она предоставляет, конечно же, набор фильтров для базовых трансформаций изображения, но не имеет обычных функций редактирования картинок. Вместо этого Impict предоставляет возможность вставки векторных, текстовых объектов и фигур для придания снимкам экрана большей информативности и привлекательности". И, надо сказать, с этой задачей Impict справляется великолепно.

Кроме описанных выше утилит, вместе с Help & Manual поставляется комплект компонентов Delphi/C++ Builder, позволяющий легко связать справку с разрабатываемым приложением: добавить подсказки "What's this?" ("Что это такое?"), связать определенные разделы справочной системы с определенными окнами или элементами управления, чтобы пользователь мог вызвать справку, как говорится, "легким движением руки" (т.е. по нажатию на F1). Компоненты эти, как, впрочем, и все остальные части Help & Manual, снабжены подробной справочной системой и примерами использования. С более ранними версиями Help & Manual также поставлялись эти компоненты, однако сейчас они, по заверениям разработчиков, существенно переработаны и включают поддержку последних версий Borland Delphi и C++ Builder.

Вот такая хорошая, удобная и вообще белая и пушистая программа, полезная каждому разработчику от мала до велика. Но в каждой бочке меда есть своя ложка дегтя. Не минула чаша сия и Help & Manual.

Во-первых, для создания справочной системы в формате HTML Help (как 1.x, т.е. CHM, так и для 2.0) придется скачивать с сайта "Майкрософта" HTML Help Workshop. Вроде бы, мелочь, но досадно. А вот крупное огорчение - это цена Help & Manual. Разработчики, имя которым EC Software, оценили свой труд в $299. Впрочем, нельзя сказать, что программа этих денег не стоит. Ну и последний пункт этого списка - отсутствие русифицированной (и, тем более, белорусифицированной) версии Help & Manual 4. Третья версия есть, а вот четвертая отсутствует. Что ж, будем ждать - может, скоро переведут.

Для тех, кто еще сомневается, сообщу следующую информацию: этот продукт три года подряд был победителем в номинации "Help Authoring Package" (пакет для разработки справочных систем) Shareware Industry Award (www.sic.org/2005nominees.asp) - самой престижной премии, которой награждаются Shareware-программы.

Вадим СТАНКЕВИЧ

1 WYSIWYG - What You See Is What You Get, т.е. в редакторе текст выглядит так же, как в окне просмотрщика справки

Версия для печатиВерсия для печати

Номер: 

15 за 2006 год

Рубрика: 

Software
Заметили ошибку? Выделите ее мышкой и нажмите Ctrl+Enter!

Комментарии

Аватар пользователя Andrei
"этот продукт три года подряд был победителем в номинации "Help Authoring Package" (пакет для разработки справочных систем)"

Пробовал эту программу дважды, с перерывом в пару лет (правда, не последнюю версию). Выглядит навороченно, но... Оба раза она не смогла сконвертировать таблицы из формата winhelp (rtf) в chm (html). И еще какие-то проблемы были, не помню точно. В общем, оба раза я удалил ее через полчаса после установки из-за корявости. Уж лучше делать вручную, чем разбираться с этой кривой прогой. И за что же такое она была победителем? Видимо, конкуренты были еще хуже.

Аватар пользователя Andrew
Утилита - лучшая в своей нише. Лет 5 тому назад, скачал десяток подобных утилит. Протестировав все - выбрал Help & Manual
Аватар пользователя Вадим Станкевич
Andrei, Вы сами пробовали написать конвертер из RTF в HTML и обратно? Очень непростое занятие.

Конкуренты? Да, они ещё хуже, Вы правы. Если только RoboHelp...

Аватар пользователя Ирина
Попробовала создать справку в H&M, очень удобно, одна проблема при компиляции вместо русских букв знаки вопросов..................
Аватар пользователя Вадим Станкевич
А Вы указывали в параметрах русскую кодировку?
Аватар пользователя ОлдСпайс
А кто может знает где можно взять русификатор к этой проге?

Я че-то искал, но не нашел

Аватар пользователя Ирина
Да, кодировку указывала. На самом деле легко победить проблему: при просмотре, правой кнопкой мыши "В виде HTML" можно все поправить:-) Теперь проблема № 1 просмотр файла с сетевого диска: слева дерево отображается, а справа "Невозможно отобразить страницу", поискала по форумах, пишут:

"Читай здесь http://helpman.it-authoring.com/viewtopic.php?t=3364.

Вкратце: Обновление Microsoft 896358 для WinXP, в Windows Vista - речь идет о висте и о xp с патчем 896358

по умолчанию не

позволяет открывать CHM-справки с сетевых дисков.

Надо добавить ключ в реестр:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTMLHelp\1.x\ItssRestrictions]

"UrlAllowList"="file://путь chm-файла"

". Мне не помогло к сожалению:-(((

Аватар пользователя Дмитрий Смирнов
Поглядите, если интеренсо мой инструмент, который заточен на использование веб-разработчиками.

http://www.bulldoc.ru

BullDoc — это система для создания документации. Представляет собой комплекс на php, который можно использовать без веб-сервера через командную строку, или в виде сайта под управлением apache. Исходники документации хранятся в текстовых файлах и могут быть помещены в svn. Документация экспортируется в полностью статический html(один файл на одну страницу или один монолитный файл), для размещения на сайте и для скачивания. Имеется экспорт в файл справки chm.