«Документальный» плюс

Денис Колисниченко

Спецвыпуск: Хакер, номер #053, стр. 053-048-1

(dhsilabs@mail.ru)

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

С чего начать?

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

- формат HTML – документацию в формате HTML прочитают пользователи любой операционной системы;

- формат PDF (Portable Document Format) – формат PDF тоже поддерживается всеми операционными системами;

- стандартный файл справки Windows (.hlp) – поддерживается всеми версиями Windows, начиная с Windows 95;

- компилированный файл справки (.chm) – поддерживается ОС Windows, начиная с версии Windows 98;

- Формат man – поддерживается ОС UNIX/Linux.

Подробнее рассмотрим каждый из вариантов.

Сделанную в HTML документацию смогут прочитать пользователи любой операционной системы – Windows, Linux, MacOS. Выложить на сайт такую документацию, "одев" в дизайн сайта – без проблем. Впоследствии из формата HTML с помощью вспомогательных программ сможешь конвертировать документацию в форматы .chm и man. Именно в силу этих причин я считаю, что сам текст документации лучше сначала писать в формате HTML. При написании документации в формате HTML помни: используй формат HTML 3.2, воздержись от лишних "наворотов", лучше без стилей и обязательно без JS и VBS, чтобы потом не было проблем при конвертировании.

Документация в формате PDF не приветствуется. Во-первых, для ее просмотра нужно будет установить Acrobat Reader, что увеличит размер дистрибутива. А по правилам хорошего тона ты обязан включить его в состав дистрибутива: у тебя же коммерческая программа – вдруг у пользователя не окажется Acrobat Reader, тогда раздастся звонок в службу поддержки. А что если таких пользователей будет 1000? Во-вторых, для создания такой документации нужен Acrobat, который, в отличие от Acrobat Reader, не бесплатен. Документацию в формате PDF нужно использовать когда ты разрабатываешь мультиплатформенный продукт. Именно для этих целей и был разработан формат PDF: документация в нем будет отображаться одинаково на разных платформах: любой шрифт, картинку в любом формате можно включить в PDF-файл, и ты можешь быть уверенным на все 100%, что у пользователя он будет выглядеть так же, как и у тебя. В-третьих: размер PDF-файла. Он не такой уж большой, но может случиться, что хорошая документация в PDF-файле займет больше места, чем сама программа. При нынешних дисковых объемах это ничем страшным не грозит, но при загрузке программы при соединении в 33,6 Кб разница в 2 Мб + Acrobat Reader довольно ощутима.

Формат HLP (стандартный файл справки Windows) тоже лучше не использовать. Windows 95 уже практически не используется, а справка в формате CHM выглядит свежее и привлекательнее, чем в формате HLP. Для просмотра CHM-файлов нужна не столько Windows 98, сколько Internet Explorer версии 4 или выше, который обычно не входит в состав Windows 95. Если учитывать поправку о Windows 95, в состав дистрибутива нужно добавить справку в формате HTML – много места она не займет. При создании ярлыков в программной группе в программе инсталляции нужно создать два ярлыка для справочной системы - один для CHM-формата, другой для HTML. А в обработчик события, отвечающий за вызов справочной системы, нужно поместить код, который проверял бы версию Windows и запускал бы нужную справочную систему.