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

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

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

При создании справки для Linux-программы используют два формата: man и HTML. Первый формат – это традиция, которую вредно нарушать, а HTML примечателен тем, что можно создать внешне привлекательную справку, да еще и с картинками - как говорится, лучше один раз увидеть, чем сто раз услышать. Создание документации для Linux-программы – это отдельный разговор, но мы еще к нему вернемся, а пока о том, как нужно правильно писать документацию.

На чьи плечи возложить эту задачу?

Писать самому или платить опытному техническому писателю, написавшему с десяток разных руководств? Если ты не чувствуешь в себе писательского таланта, лучше путь напишет опытный человек. Но имей в виду, что хорошая документация стоит довольно дорого и за нее тебе, возможно, придется выложить намного больше, чем стоит один экземпляр твоей программы. Например, цены на полное руководство твоей программы могут варьироваться от $500 до 1200, а может, и того больше – все зависит от сложности продукта. Программа может стоить всего $50 – тебе нужно будет сразу заплатить в десять раз больше (и это минимум). Могу предложить небольшой трюк: если твоя программа стоит $50, подними стоимость до $55-ти, и первые десять дистрибутивов окупят вложения в документацию. За документацию ты платишь один раз.

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

Правильная документация

С форматом справки мы уже определились – это HTML, поскольку его можно использовать в сыром виде или преобразовать в любой другой формат. Для написания документации лучше использовать самый обыкновенный текстовый редактор, например, "Блокнот", чтобы не было соблазна влепить пару спецэффектов, которые или не будут поддерживаться браузером пользователя, или не скомпилируются при создании CHM-файла.

Структура

Прежде всего потрать немного времени и на листочке набросай структуру твоей справки так, как она отображалась бы слева в окне системы помощи, например:

Листинг

Программа версия 1.1.

Описание программы

Что нового в версии 1.1

+Быстрый старт