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

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

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

+Расширенные функции

+Администрирование

+Обновление

…

Служба поддержки

Если тебе трудно написать структуру системы справки с ходу, в качестве разделов системы справки используй пункты меню твоей программы и опиши последовательно все меню – пункт за пунктом:

Листинг

Программа 1.1

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

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

-Меню

+Меню Файл

+Меню Правка

+Меню Вид

+Меню Отчет

+Меню Сервис

+Окно

…

Второй вариант – это описать какой-нибудь пример работы с программой. Например, если твоя программа предназначена для автоматизации рабочего места менеджера и если ее основными функциями являются формирование счета-фактуры, накладной, договора – так и описывай, в таком же порядке:

Листинг

Программа 1.1

…

-Работа с программой

Формирование счета-фактуры

Формирование накладной

Формирование налоговой накладной

Договора

Список счетов

Список накладных

Склад

Отчет по складу

-Дополнительные функции

Фильтры

SQL-запросы

…

Думаю, этой информации будет вполне достаточно, чтобы набросать удобную структуру. И еще два совета относительно структуры.

1) Не поленись и создай предметный указатель: очень помогает при поиске какой-нибудь функции в файле справки.

2) Если модуль администрирования твоей программы является отдельным приложением, создай для него отдельный файл справки.

Полнота и читабельность документации

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

- Ко мне не доходят сообщения.

- А вы прочтите их еще раз :-) .

Старайся сделать так, чтобы твоя документация была написана понятным языком. Пример неправильно написанного фрагмента документации: "Если не работает функция GetObjAddr, зарегистрируйте библиотеку comdlg32o.dll и пропишите ее в файле proga.ini.". Что здесь не так? Вроде все понятно. Будь это shareware или freeware-программы, такой текст бы прошел. Но коммерческая программа - совсем другое дело. Прочти этот пример еще раз и еще раз. А теперь представь лицо начинающего пользователя, который только научился дискету вставлять куда положено, когда он видит сообщение об ошибке, а потом пытается найти ответ в справке и видит этот текст. Представил? При большом количестве пользователей твой телефон покраснеет от входящих звонков. И ты, вместо того чтобы исправлять ошибки в своей программе или разрабатывать к ней полезные плагины, будешь консультировать и пользователей, и администраторов, разъясняя написанную документацию, а это, поверь, не очень благодарная работа.

Поэтому нужно писать ясно, чтобы не было двойственных ассоциаций и чтобы написанный текст не порождал больше вопросов, чем было до его прочтения. А в этом случае так оно и есть. Читаем: "Если не работает функция GetObjAddr". Откуда пользователь знает, работает она или нет. Лучше укажи точное название ошибки и диагностическое сообщение, которое увидит пользователь. А еще лучше промоделировать ситуацию и сделать скриншот этой ошибки, который потом можно "вставить" в документацию.