Как писать документацию

Прежде чем писать документацию, нужно определить ее будущую структуру, т. е. из каких разделов она будет состоять.

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

Для решения первой задачи, т. е. помощи пользователям в преодолении различных проблем с освоением и работой с программой, следует включить в документацию раздел Introduction (Введение), в котором рассказать о назначении программы, а также гораздо более объемный раздел Description (Описание), в котором дать описание меню, диалоговых окон и прочих элементов программы.

Считается, что для составления текста справочных систем применяются два подхода: либо вы рассказываете для чего что-то предназначено, либо о том, как что-то сделать (wanting to know vs. wanting to do). Однако, на мой взгляд, при определении структуры и содержания Справки эти два подхода нужно объединить и добавить в документацию раздел How to... (Как сделать...). Дело в том, что все вопросы, с которыми пользователи обращаются к справочной системе, можно разделить на две группы: "Что означает этот элемент (меню, кнопка, флажок и т. п.)?" и "Как мне сделать то-то (отфильтровать данные, переформатировать текст, настроить параметры и т. п.)". Если же в документации будет только описание элементов программы, то на вопросы категории "Как мне сделать то-то?" найти ответ для не очень опытных пользователей будет гораздо сложнее.

Кроме того, нужно создать в Справке раздел Technical Support (Техническая поддержка), где указать адреса e-mail, по которым пользователи могут задать свои вопросы, а также привести ссылки на источники дополнительной информации о программе, если они имеются: форум на Web-сайте, список ответов на часто задаваемые вопросы (FAQ) и т. п.

Для отражения в документации принадлежности программы к shareware-программы следует создать раздел Registration (Регистрация), где завести подразделы, в которых рассказать о цене программы, дать ссылки на Web-сайты компаний-регистраторов, указать преимущества статуса зарегистрированного пользователя (например, бесплатные обновления, отсутствие ограничений функциональности программы) и другую информацию по этой теме.

Если у вас имеется несколько shareware-продуктов, то удачным шагом будет создание еще одного раздела: Our products (Наши продукты), где будет дана информация о ваших других программах и ссылки на их Web-страницы и файлы для загрузки. Эта информация будет полезна для тех пользователей, которые получили дистрибутив программы не с Web-сайта разработчика (а, например, скачали его с сервера интернет-архива или купили в составе сборника shareware-программ на CD-ROM) и ничего не знают о других продуктах этого же автора. Очень часто бывает, что люди начинают интересоваться ими, скачивают, тестируют и — оплачивают регистрацию.

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

Для российских программистов, составляющих справочную систему, большая проблема — английский язык. Одно дело меню и небольшие информационные сообщения в интерфейсе программы, здесь больших сложностей нет (хотя в некоторых российских программах даже в меню и диалоговых окнах встречаются ошибки). Но вот документация... Здесь требуется более глубокое знание языка. Грамматические и орфографические ошибки очень сильно портят впечатление обо всем продукте, и это приводит не только к отрицательным обзорам в журналах и на Web-сайтах, но и существенно снижает объем продаж. Качественный английский язык документации -одно из самых главных требований к серьезному shareware-продукту.

Самый простой вариант, на котором останавливается большинство авторов, — это перевод текста на английский язык знакомым или нанятым за плату переводчиком. Лучше всего будет после этого разместить на Web-сайте программ объявление с предложением для пользователей из Великобритании или США проверить имеющийся у вас перевод документации в обмен на бесплатную регистрацию копии вашей программы. Человек, для которого английский язык является родным, сможет наиболее эффективно довести качество перевода до хорошего уровня.

Некоторые начинающие разработчики, стараясь сильно не занимать себя проблемой написания качественной справочной системы на хорошем английском языке, проступают так: находят аналогичный продукт и почти полностью копируют его документацию, заменяя разве что название программы и ссылки на сайт разработчика. Хотя идея получить с минимальными затратами времени и сил профессиональную англоязычную справочную систему очень заманчива, делать этого ни в коем случае нельзя. Это обычное нарушение авторских прав, иными словами — плагиат. Рано или поздно это все равно раскроется, восстановить потерянную репутацию в глазах пользователей, обозревателей, работников shareware-сервисов будет очень трудно.

Один из российских разработчиков shareware рассказывал такую историю. Некий иностранный программист, продававший конкурирующую программу (утилита для общения в локальной сети), украл у него полностью всю документацию, включив ее в дистрибутив своего продукта. Однако он забыл исправить адреса, на которые указывали ссылки в Справке: текст на них был изменен, но вели они по-прежнему на оригинальный Web-сайт. Пострадавший от плагиата смотрел на это сквозь пальцы, т. к. его программа продавалась очень хорошо, и мелкий конкурент его не особенно волновал. Но однажды он получил письмо от пользователя, который интересовался, почему ссылка из документации программы, которую он недавно приобрел, ведет на совсем другой сайт, где продается вроде бы похожий продукт. "Это что, новая версия?" - спрашивал удивленный пользователь. Наш соотечественник объяснил ему ситуацию и предложил этому человеку, т. к. он уже купил программу плагиатора, скидку (в 20%) при переходе на свой продукт. Пользователь согласился: воров никто не уважает.

Содержание раздела