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

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

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

Читаем дальше: "зарегистрируйте библиотеку comdlg32o.dll". Это предложение порождает вполне обоснованный вопрос пользователя: "А как это сделать?" Будь уверен: в этом случае он к тебе точно позвонит, чтобы узнать, как зарегистрировать эту библиотеку. И еще: а что если пользователь не знает, что такое библиотека. Встречаются и такие экземпляры. Поэтому правильнее написать: "Выберите команду меню "Пуск", "Выполнить" и выполните команду":

Листинг

regsvr32 comdlg32o.dll

Старайся употреблять поменьше технических терминов. А если употребляешь их, обязательно вставляй примечание, в котором объясняешь что к чему. Только избегай в определении других технических терминов, не известных пользователю, а если и от этого не сможешь удержаться, объясни их. Так повторяй до тех пор, пока не останется ни одного непонятного пользователю. Если примечаний наберется очень много – выдели их в отдельный файл, который назови глоссарием.

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

Итак, после небольших трансформаций текст "Если не работает функция GetObjAddr, зарегистрируйте библиотеку comdlg32o.dll и пропишите ее в файле proga.ini." будет выглядеть так:

Ошибка 110: Недоступна функция GetObjAddr[:COMDLG32O].

Попробуйте выполнить следующие действия:

1) Определите место нахождения файла COMDLG32O.DLL. Обычно данный файл должен находиться в каталоге:

C:\Program Files\My Company\My Proga\Libs\COMDLG32O.DLL

Чтобы убедиться в этом, выполните команду основного меню Windows "Пуск", "Найти файлы и папки". В окне поиска в поле "Имя" введите COM32DLGO.DLL. Когда файл будет найден, запомните или запишите, в какой папке он расположен. Если файл не найден, попросите администратора переустановить программу.

2) Нажмите на кнопку "Пуск" и выберите команду "Выполнить". Появится окно "Запуск программы". В поле "Открыть" введите команду:

regsvr32 <папка>\comdlg32.dll

где <папка> - это имя папки, в которой расположен файл COMDLG32O.DLL

3) Запустите "Блокнот" и откройте файл C:\WINDOWS\MY_PROGA.INI. В конец этого файла добавьте строку:

COMDLL32O.DLL

Если ошибка не исчезла, обратитесь в службу поддержки.

Если ты заметил, вышеприведенный текст написан в стиле

Чтобы получить Х, выполните

A)

B)

C)

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