Содержание
1 Введение
В линукс-сообществе популярной тенденцией становится использование
графического интерфейса в любой программе. Результат -- все больше и больше
авторов применяют в своих программах графические диалоги конфигурации.
Есть одно важное но: при использовании графического интерфейса создается
впечатление, что документация не нужна. Человек, который может сделать что-то
просто кликнув мышкой, часто думает: "Зачем читать документацию? Покликал
туда-сюда -- и все заработало!"
Но я бы, наоборот, подтолкивал людей к чтению документации. На
самом деле, чем лучше документация -- тем проще работать с программой. Примером
может быть web-сервер Apache -- он поставляется с очень серьезной и объемной
документацией. В результате любой понимающий по-английски может настроить и
использовать Apache, причем без графического интерфейса, основанного на "мышиных
щелчках".
Эта статья является попыткой подтолкнуть программистов к документированию
своих проектов, а также дать общую идею, как это делать (и некоторые конкретные
советы).
2 А зачем писать документацию к
программе?
Тому есть множество причин! Чем подробнее документация, тем проще
пользоваться программой. Чем больше всего документировано, тем выше качество
встраиваемых дополнительных модулей. Чем больше документации, тем лучше
чувствуют себя конечные пользователи. Как только пользователь испытывает
сложности с какой-либо функцией в программе -- он начинает читать сопровождающую
ее документацию. Очевидно, что структурированная и хорошо написанная
документация позволит пользователю быстро овладеть нужной функцией [в
оригинале -- фичей:) прим. редактора.].
3 Что в проекте должно быть
документировано?
В общем случае, должны быть документировано следующее:
- Основы пользования программой должны быть изложены в странице руководства
(man page).
- Более сложные аспекты работы с программой можно объяснить, перечислив в
сопровождающей прогамму документации ВСЕ опции настройки с примерами их
использования (документация к Apache, опять-таки, будет хорошим примером).
- И, конечно, исходынй код должен быть снабжен комментариями, потому что
кто-то может захотеть внести в программу дополнительные возможности.
- В примерах использования должен быть работающий и подробно
документированный конфигурационный файл.
- Описание установки, ведь не все программы работают с
./configure && make && make
install.
- Описание пользовательского интерфейса, особенно, если это не типичная
"мышетычка" [point-and-click].
Список можно продолжить. Но, в общем, хорошая документация должна отвечать
указанным требованиям (как минимум) и быть читабельной.
4 Как пишется документация?
Используйте ваш любимый редактор. Документы в предлагаемых мной форматах
можно создать при помощи простого текстового редактора.
Очень важен стиль. Документация должна быть легко читаемой. Не пишите в
стихах.
Рекомендуемый для написания документации язык -- простой английский. Это
связано с тем, что работающие с компьютерами люди как правило понимают
по-английски. Всегда можно (и нужно - Прим.Пер.) добавить
документацию на своем родном языке. Но помните, что не все понимают по-немецкии
или по-русский. По меньшей мере, описывайте на английском основную
функциональность вашей программы. Человек, который не может понять даже
элементарные части описания, не будет читать его дальше и, чаще всего, вообще не
будет использовать программу.
Остальное -- на ваше усмотрение. Помните, что написание документации -- самая
мерзкая часть разработки программного обеспечения.
5 Какой формат использовать?
5.1 Подходящие файловые форматы
Используйте стандартные форматы. Никто не любит закрытых форматов. Поэтому MS
Word, StarOffice и все аналогичное ПО сразу отпадает.
Наиболее простой формат -- это обычный текст. Его можно прочесть где угодно,
и для этого всегда можно использовать любимый редактор или вьюер.
Если вы хотите, чтобы документация была пригодна для качественной печати,
неплохим выбором будет LATEX. Его
относительно просто использовать, во всяком случае, для написания технической
документации. Достоинства документации, написанной в LATEX --
системо-независимый формат и хорошие возможности для форматирования текста (Все
равно, это напоминает стрельбу с ракетного рейсера по птицам. -
Прим.пер.). Получившийся файл даже можно экспортировать в HTML.
На сегодня наиболее подходящим форматом является HTML. Это связано с тем, что
браузеры существуют на всех платформах, а кроме того, вы можете без изменений
разместить документацию на web-сайте.
Можно использовать и SGML- или XML-основанный формат, вроде DocBook и
LinuxDoc/SGML. Они предлагают большУю гибкость при конвертации в другие
форматы (включая такие, которых еще не изобретены), удобны для автоматической
обработки текста, но их освоение требуют такого же времени, как и
LATEX.
5.2 Документирование исходного
кода
Исходный код можно просто документировать достаточным количеством
комментариев и использованием для переменных подходящих имен. Очень важно
отдельное описание API, особенно, если вы пишете библиотеку функций или что-либо
расширяемое.
6 Докуменитация в формате HTML
Всегда используйте самое общепринятое подмножество тэгов HTML. Не применяйте
фреймы и Javascript. Используйте тэги <H1></H1> -
<H6></H6> для секций и <P></P> для абзацев. За деталями
обратитесь к HTML-Howto.
7 Использование LyX
Это мой личный совет для технических писателей. LyX основан на идее
"то-что-ты-видишь-это-то-что-ты-подразумеваешь" [WYGIWYM -- what you get is what
you mean], а результат получается в формате
LATEX, который без труда
экспортируется в ASCII и HTML. Это своего рода графический фронт-энд для
LATEX. Но надо помнить, что LyX -- не
редактор WYSIWYG (то-что-ты-видишь-это-то-что-ты-получишь, what you see is what
you get).
LyX вместе с документацией входит с большинство дистрибутивов Linux.
Попробуйте -- он легок в применении, а результаты просто ошеломляют.
Вообще, возможности экспорта в LyX делают его хорошо приспособленным для
написания документации. Можно сделать из документации .dvi-файл, и тогда ее
печатную версию можно будет получить на любой Linux-машине с настроенной
системой печати.
8 Как насчет PDF?
PDF -- это расширенная версия Postscript. Главный недостаток этого формата в
том, что для просмотра нужет графический дисплей или принтер.
На Linux PDF реализован неважно, в то время, как HTML файлы и страницы
руководства man -- "просто работают". Файлы
LATEX всегда работают, если правильно
установлено соответствующее ПО. Но PDF'ы, созданные с помощью разных программ,
часто оказываются несовместимы с различными "гляделками" [viewers], и все может
закончится тем, что кто-то не сможет открыть ваш документ или увидит "пустой
лист".
Кроме того, PDF файлы обычно огромны, особенно если в них есть картинки и
таблицы. Отображение PDF файлов, по сравнению с HTML, DVI и простым текстом,
очень медленное. Вы, конечно, можете использовать PDF, но я не рекомендую его
использование для составления программной документации.
9 Заключение
Если использовать правильно подобранные инструменты, то написание
документации может стать приятным занятием. Помните -- документация должна быть
написана так, что бы ее мог прочесть кто угодно.
Теперь -- вперед! Хорошая документация -- гарантия успеха.
Матиас Арндт (Matthias Arndt)
Я линукс-энтузиаст из северной Германии. Я люблю старый рок-н-рол 50-х
годов, люблю писать статьи для Linux Gazette. Сейчас я учусь
на факультете информационных технологий с экономическим уклоном.
Copyright (C) 2001,
Matthias Arndt.
Copying license http://www.linuxgazette.com/copying.html
Published
in Issue 71 of Linux Gazette, October 2001
Команда переводчиков:
Владимир Меренков, Александр Михайлов, Иван
Песин, Сергей Скороходов, Александр Саввин, Роман Шумихин, Александр
Куприн
Со всеми предложениями, идеями и комментариями обращайтесь к Сергею
Скороходову ([email protected])
Сайт рассылки: http://gazette.linux.ru.net
Эту статью
можно взять здесь: http://gazette/linux.ru.net/lg71/articles/rus-arndt.html
| 