Виды документации

Текстовый файл

Чисто теоретически, документация может быть выполнена в виде обычного текстового файла — например, readme.txt. Однако для серьезной программы один текстовый файл — явно недостаточно. В крайнем случае, readme.txt может быть временной заменой справочной системы на этапе, когда программа существует в виде бета-версии. У готового же к продажам продукта документация должна быть оформлена в одном из форматов, специально предназначенных для справочной системы.

В то же время файл readme.txt тоже должен входить в дистрибутив програм­мы, служа важным дополнением "основной" документации. Readme.txt обычно содержит краткую информацию о продукте: номер версии, дата вы­пуска, имя разработчика, адрес домашней страницы, важные заметки о текущем выпуске (новые возможности, необходимость установки каких-либо компонентов и т. п.). Особенности, из-за которых формат ASCII не подхо­дит для создания полноценных справочных систем — отсутствие возможностей для удобной навигации по страницам и поиска, — здесь являются дос­тоинством. Благодаря им, пользователь может быстро получить доступ к важной информации, не путаясь в многочисленных страницах традиционной справочной системы.

WinHelp

WinHelp  — настоящий долгожитель среди форматов справочных систем. Программа winhelp.exe, обеспечивавшая работу HLP-файлов, входила в состав еще шестнадцатиразрядных версий Windows. Несмотря на свой почтенный возраст, WinHelp — довольно эффективный формат для органи­зации документации: он позволяет хранить в HLP-файлах форматированный текст (включая таблицы, списки и тому подобные элементы), графику, ви­део, анимацию, звук, проводить поиск, индексировать справочный файл для более эффективного поиска.

У WinHelp очень мало недостатков. Один из самых серьезных — невозмож­ность печати всего справочного файла целиком, в результате чего приходит­ся посылать на принтер каждый раздел отдельно. Другой минус — то, что каждый экземпляр справочной системы может состоять из пяти файлов: не слишком изящный способ организации документации.

Таблица. Файлы справочной системы в формате WinHelp

В целом формат WinHelp достаточно удобен и универсален, и поэтому, не­смотря на появление нового формата — HTML Help, активно продвигаемого Microsoft, WinHelp по-прежнему очень популярен среди разработчиков справочных систем.

HTML Help

HTML Help  — новый формат файлов для документации, разрабо­танный Microsoft как замена "старичку" WinHelp. Первой операционной системой, в которую был включен HTML Help, стала Windows 98.

HTML Help отражает новую политику Microsoft: во-первых, полная инте­грация приложений с Интернетом, во-вторых, использование HTML как основного формата файлов: в процессе подготовки справочной системы разработчик должен сохранять текст в формате HTML, а для просмотра по­лучившегося после компиляции СНМ-файла требуется, чтобы на компьюте­ре пользователя был установлен интернет-браузер Microsoft Internet Explo­rer 3.02 или выше. Впрочем, некоторые специалисты восприняли появление HTML Help скептически: разработка нового формата, по их мнению, были обусловлена не заботой о пользователях, а желанием Microsoft добиться пе­релома в так называемой "войне браузеров" и добиться преимущества над основным конкурентом своего Internet Explorer — Netscape Navigator (в то время большая часть рынка интернет-браузеров принадлежала "Навигатору").

В HTML Help устранены недостатки предшественника: можно распечатать не только текущий раздел, но и все его подразделы: вся справоч­ная система находится не в пяти, а всего одном файле с расширением chm. Правда, исчезла полнотекстовая индексация файла, и возможности поиска в Справке несколько снизились.

Примечание

Некоторые авторы прикладывают в качестве документации к своим програм­мам просто несколько HTML-файлов, без компиляции их в СНМ-файл формата HTML Help. Это, конечно, не может являться полноценной заменой HTML Help: скорее, это некоторый промежуточный вариант между текстовым файлом readme.txt и "настоящей" Справкой.

Существует также несколько аналогичных форматов HTML Help, также ис­пользующих язык HTML для описания структуры справочной системы: NetHelp от компании Netscape, WebHelp от Oracle и, наконец, JavaHelp от Sun. Однако эти форматы не получили сколько-нибудь широ­кого распространения и используются в основном в продуктах соответст­вующих фирм-разработчиков.

Adobe Acrobat

Adobe Acrobat  был разработан компанией Adobe как более эффек­тивная альтернатива HTML. Как известно, основное достоинство HTML — независимость платформы: HTML-документ можно прочитать на компьюте­ре с любой операционной системой, главное, чтобы было установлено средство просмотра HTML-файлов. Однако при этом документ выглядит на раз­ных компьютерах по-разному: это зависит от установленных на компьютере пользователя шрифтов и других системных настроек, а также названия и версии средства просмотра HTML. Как известно, страница, отлично ото­бражаемая в Internet Explorer, может вообще не показываться в Netscape Navigator, и наоборот. А уж многочисленные мелкие, но раздражающие ис­кажения, которые возникают при просмотре страниц в разных браузерах, давно стали предметом горячих споров в интернет-конференциях.

Adobe Acrobat, по замыслу разработчиков, и предназначен для решения этой проблемы: документы в этом формате можно просмотреть не только в лю­бой операционной системе (существуют версии этого продукта для Windows, MacOS и Unix), но именно в том виде, как задумывал его автор. При этом пользователю доступны гораздо большие возможности, чем предоставляют WinHelp или HTML Help: можно распечатать весь документ целиком, мас­штабировать не только текст, но и графику, поворачивать страницы на 90 градусов и др.

Adobe Acrobat (расширение файлов — pdf) очень популярен как формат для хранения документации к различному компьютерному "железу": материн­ским платам, видеокартам, акустическим системам и т. п. Среди разработ­чиков программного обеспечения  он не очень распространен, хотя некоторые крупные компании (например, McAfee, Sy­mantec) используют его для подготовки справочных систем к своим про­дуктам.

На мой взгляд, минусы Adobe Acrobat, которые препятствуют его использованию в качестве средства организации Справки для программ, следующие:

Документация на Web-сайте

Некоторые разработчики слишком буквально понимают термин "online help", который на самом деле обозначает справочную систему в электронном, а не печатном, виде. Поэтому при нажатии клавиши <F1> или вызова меню Help в их программе, запускается установленный в системе интернет-браузер и загружает... раздел "Справка" с Web-сайта разработчика программы!

Это пример того, как не следует делать документацию. Ведь у пользователя она всегда должна быть под рукой, а размещение справочной системы в Интернете часто приводит к тому, что пользователь не может получить к ней доступ тогда, когда ему требуется помощь. Например, пользователь мо­жет скачать программу дома, а использовать ее на работе, где по каким-либо причинам выход в Интернет может отсутствовать, и наоборот. И даже если доступ в Интернет на компьютере имеется, то домашнему пользователю для выяснения каких-то деталей относительно работы с программой нужно доз­ваниваться до интернет-провайлера, что при частых обращениях к справоч­ной системе очень раздражает. Кроме того, скорость доступа к справочной системе, размещенной в Сети, не сравнима со скоростью чтения файла Справки с жесткого диска компьютера. И наконец, не нужно забывать, что за пользование Интернетом провайдеры берут деньги, а значит, доступ к справочной системе программы тоже будет платным!

WinHelp или HTML Help?

Как видно из предыдущего раздела, сегодня существует два реальных вари­анта для реализации справочной системы: WinHelp и HTML Help. Какой же из них предпочесть?

Возможности

Конечно, по функциональности справочной системы HTML Help значи­тельно опережает своего предшественника. К услугам разработчика все то, что поддерживает браузер Microsoft Internet Explorer: не только "обычный" HTML, но и Dynamic HTML, таблицы стилей (CSS), JavaScript и т. д. С по­мощью этих инструментов можно реализовать такие функции, которые WinHelp и не снились,

Однако за все нужно платить, и "красоты" HTML Help — не исключение Дело в том, что, включив в оформление документации все эти "навороты", автор не может быть уверен, что на компьютере пользователя справочная система отобразится корректно. Вид Справки может быть самый различный: от небольших искажений до полной нечитабельности. Это зависит от мно­гих факторов, например, от версий браузера, установленных у автора и у пользователя. Например, если у пользователя более старая версия, чем у ав­тора, то многие элементы справочной системы могут быть невидимыми Другой вариант — персональные настройки браузера, например, запрет выполнения JavaScript или установленный специфический шрифт. Более того, не редки случаи, когда на компьютере вообще не установлен Internet Explo­rer, и просмотр файла HTML Help невозможен. Например, один из россий­ских программистов рассказывал, что ему пришлось отказаться oт формата HTML Help в пользу WinHelp из-за того, что ему стали приходить письма от пользователей примерно такого содержания: "В фирме, в которой я работаю, корпоративная политика состоит в отказе от Internet Explorer, и со всех компьютеров этот браузер удален и установлен Netscape Navigator.

Вследствие этого я не могу просмотреть Справку к Вашей программе. Вы­шлите, пожалуйста, мне ее текст в каком-нибудь другом формате".

В то же время большинство разработчиков не пользуются и 10% всех воз­можностей Internet Explorer, предпочитая привычные средства подготовки документов: перекрестные ссылки, форматированный текст, таблицы, спи­ски, графические изображения. А со всем этим превосходно справляется и WinHelp. Кроме того, у последнего перед HTML Help есть даже некоторые преимущества именно в области создания справочных систем. Например, во всплывающих (popup) окнах WinHelp допускает форматированный текст, а HTML Help — нет. Интересно, что в этой ситуации специалисты Microsoft советуют продолжать пользоваться WinHelp.

Скорость работы

Как уже упоминалось, для чтения СНМ-файлов формата HTML Help ис­пользуется браузер Internet Explorer, который вызывает много нареканий за высокие требования к системным ресурсам и относительно медленную ра­боту. Действительно, при вызове Справки в формате HTML Help, особенно имеющей довольно большой объем, задержки в работе по сравнению с WinHelp хорошо заметны.

 

Перспектива

Здесь, конечно же, все козыри у HTML Help, который создан как замена WinHelp и усиленно продвигается Microsoft. Нет сомнений, что в будущем имеющие недостатки HTML Help будут устранены, а функциональные воз­можности — еще больше расширены. Более того, я думаю, что HTML Help изменит существующий подход к созданию документации и, возможно, серьезно поменяет вид и структуру справочных систем.

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

Какой же формат выбрать? Каждый, конечно же, решает сам. Лично я пока остановился на WinHelp. Меня привлекает его надежность (независимость от установленного в системе интернет-браузера и стопроцентная его под­держка во всех версиях существующих Windows), высокая скорость работы, хорошие возможности для создания файлов Справки (пока я не чувствую потребности в Dynamic HTML или JavaScript). To, что WinHelp — уже "старичок" по сравнению с модным HTML Help, на мой взгляд, даже плюс: пользователи уже привыкли к нему и работают с такими справочными сис­темами без проблем.

На самом деле не нужно бояться сделать неправильный выбор и предпо­честь "не тот" формат документации. Большинство современных программ по разработке справочных систем (см. разд. "Средства создания документа­ции" данной главы) позволяют сохранять файлы как в формате WinHelp, так и HTML Help (а некоторые поддерживают еще большее число форматов) Поэтому в будущем можно без особых трудностей перейти с одного формата на другой. При желании можно даже поставлять в дистрибутиве программы документацию в обоих вариантах: WinHelp и HTML Help, позволяя пользователю самому выбрать предпочтительный формат. Программ с таким ори­гинальным решением проблемы выбора формата документации я пока не встречал, но, если бы это случилось, то лично на меня, в том числе и как на пользователя, это произвело бы большое впечатление.