Советы по грамотному написанию технической документации для пользователей.
Часть 1
В одной из предыдущих статей мы в общих чертах рассказывали, как именно происходит процесс документирования и локализации наших продуктов.
На этот раз под катом – руководство нашего технического писателя Андрея Старовойтова, которое поможет сделать вашу документацию для пользователей проще и понятнее (описанные приемы применяют при документировании своих продуктов Apple, Microsoft и другие компании).
Как известно, хорошая документация – это не роскошь, а средство увеличение объема продаж компании. Если вы собираетесь начать или уже разрабатываете какую-нибудь программу, то, чтобы выйти с ней на мировой рынок, вам понадобится руководство пользователя (оно же User’s Guide) или хотя бы документ, который расскажет покупателям, как начать работать с вашим продуктом (так называемый Getting Started with ).
На каком языке писать документацию – на русском, а затем ее переводить, или сразу на английском – решать вам. В компании Parallels мы выбрали второй подход. Зачастую намного проще сделать описание на английском, так как почти все (а сейчас уже можно сказать, что «все») компьютерные термины в русском языке заимствованы.
Далее по тексту мы остановимся как на русских, так и на английских примерах.
Итак, на что же следует обратить внимание при написании документации?
Типы топиков в документации
При написании топика, для начала надо определить, что это будет за топик :)
От этого и будет зависеть, что и как в нем писать.
Существует 4 основных вида топиков:
• Топики, которые описывают, как решить какую-либо конкретную задачу или несколько связанных между собой задач (в английском языке такой вид топиков называется task pages).
Например, «Установите Parallels Desktop» или «Выключите или приостановите Windows». В каждом из таких топиков описывается серия из одного или нескольких шагов, которые должен предпринять пользователь, чтобы добиться определенной цели. Руководство пользователя состоит преимущественно именно из таких топиков.
Обычно пользователи не любят читать, особенно когда текста много. Поэтому надо стараться делать такие топики как можно короче. Идеально, если информация будет представлена в таком виде: «вы можете сделать то-то, для этого нажмите тут и тут» (более подробно task топики будут разобраны в следующей части статьи).
Если разработчик считает, что существует какая-либо дополнительная информация, о которой необходимо знать пользователю, и ее много, то это лучше описать в концептуальных топиках (см. ниже).
• Концептуальные топики (в английском – concept pages). В таких топиках нет инструкций, как решить какую-либо задачу. Они содержат информацию, которая скорее способствует большему пониманию вещей. Например, концептуальные топики используются, чтобы:
— объяснить пользователям, как именно устроен какой-либо процесс;
— рассказать, что можно сделать в настройках приложения;
— описать добавленные фичи в новой версии продукта;
— предоставить дополнительную информацию, которая поможет пользователю лучше понять или решить какую-либо задачу.
Обратите внимание, что дополнительную информацию (в случае, если ее много) надо предоставлять именно в концептуальном топике, чтобы не перегружать task топик.
• Справочные топики (в английском – reference pages) – содержат информацию, к которой пользователь может периодически обращаться, чтобы узнать, что обозначает тот или иной термин, как работает какая-либо функция, и т.д. Хорошим примером таких топиков является словарь в конце гайда (он же Glossary). Справочные топики особенно полезны, чтобы объяснить назначение различных элементов интерфейса.
• Топики, которые описывают как решить какую-либо проблему (в английском – troubleshooting pages).
Например: «Я не могу активировать Parallels Desktop» или «Не могу подключиться к Интернету». В таких топиках описывается, что надо сделать, чтобы решить какую-либо проблему. В них же может содержаться информация, которая поможет понять, в чем причина неисправности.
Основные инструкции для всех типов документации
При создании какого-либо гайда:
1) Сконцентрируйтесь на пользователе
• Вместо того, чтобы структурировать описание продукта на его фичах или элементах интерфейса, попробуйте сконцентрироваться на задачах, которые пользователь вероятнее всего будет пытаться решить.
Например, топик о том, как защитить данные в виртуальной машине, можно назвать 2 способами:
a) «Настройки безопасности» (“Security Settings”), где подробно описать, что можно сделать для защиты данных.
b) Сделать несколько топиков, описывающих конкретные задачи:
— «Защитите данные антивирусом» (“Protect Your Data with Antivirus Software”)
— «Сделайте резервную копию виртуальной машины» (“Back Up Your Virtual Machine”)
Согласно текущим тенденциям в документировании, второй подход предпочтительнее, так как в этом случае пользователю не приходится гадать, надо или не надо что-то сделать, а он получает четкие инструкции, что же именно нужно сделать.
• Фокусируйтесь на задачах пользователя и его уровне технической грамотности.
Например, в документации для обычного пользователя вместо того, чтобы написать «Создайте виртуальную машину» (“Create a Virtual Machine”) стоит написать «Установите Windows или другую операционную систему» (“Install Windows or any Other OS”), так как термин «виртуальная машина» далеко не всем известен. Или другой пример — топик, в котором описывается, как создавать быстрые сочетания клавиш на клавиатуре, лучше назвать «Настройте комбинации клавиш» (“Configure Keyboard Shortcuts”), нежели чем «Настройки клавиатуры» (“Keyboard Settings”).
Хотя чего кривить душой, большинству читателей Хабра было бы понятнее «Настройте шорткаты», но тут уже вопрос, насколько такой термин уместен в официальной терминологии в данное время :)
• Если это может быть непонятно, объясняйте, зачем именно пользователю может понадобиться выполнить ту или иную задачу.
Например:
• При описании старайтесь использовать те слова, которые пользователь каждый день использует в своей речи. Если технически сложный термин можно заменить словами попроще, всегда старайтесь использовать более простые слова.
Например, «прозрачный» вместо «транспарентный». Если приводить пример из английского языка, то используйте «use» вместо «utilize».
2) Старайтесь дать всю необходимую информацию без лишних слов
«В Спарту пришли послы с острова Самоса — просить помощи. Они произнесли длинную и красивую речь. Спартанцы сказали: «Дослушав до конца, мы забыли начало, а забыв начало, не поняли конца». Самосцы оказались догадливы. На следующий день они пришли в собрание с пустым мешком и сказали только четыре слова: «Мешок есть, муки нет». Спартанцы их пожурили — достаточно было двух слов: «муки нет», — но были довольны такой сообразительностью и обещали помочь».
Если описать функционал слишком длинно – никто не будет его читать. Но совсем «по-спартански» тоже не подойдет, так как если будет написано слишком мало – останутся вопросы и сомнения, пользователи начнут дергать команду поддержки. В общем, тут важно соблюдать баланс.
Чтобы помочь пользователям найти всю необходимую информацию и в то же время описать каждую секцию как можно короче:
- Фокусируйтесь на самой важной информации, которая нужна, чтобы решить задачу, описанную в топике. Если какие-то детали не являются необходимыми для выполнения задачи, не надо их описывать.
- Не нужно документировать каждый клик. Если в интерфейсе и так все понятно, предоставьте пользователю самому в этом разобраться. Например, вместо того, чтобы документировать каждый шаг установки программы, лучше написать: «Для того, чтобы установить программу, следуйте инструкциям на экране». Если в качестве последнего этапа какой-либо процедуры надо нажать кнопку OK, это тоже не стоит описывать.
- Вместо того, чтобы давать всю информацию в одном топике, покажите пользователю, где можно почитать дополнительные сведения, используя ссылки на другие топики, ссылки на внешние ресурсы или же вставьте в конце секцию «Дополнительная информация» (Related Topics), в которой будут ссылки на топики, относящиеся к тому, что описано на экране.
- Если длинную задачу можно разделить на несколько этапов или подзадач, каждая из которых представляет из себя отдельную задачу, разбивайте топик на соответствующие разделы или создавайте секцию в гайде, состоящую из топиков, описывающих каждый этап. В этом случае не забывайте вставить ссылки на связанные между собой топики.
- Если какую-то задачу (например, запустить виртуальную машину) можно выполнить несколькими способами, нет необходимости описывать их все. Достаточно будет упомянуть самый быстрый и простой способ. Если вы все же считаете, что пользователю полезно знать о каком-либо другом способе, опишите его в концовке (по-английски — Outro) топика.
3) Не повторяйте одну и ту же информацию на страницах
Вместо того, чтобы в каждом топике повторять информацию, которая уже описана в каком-то другом топике, лучше ссылайтесь, что более детальное описание можно найти в таком-то топике, или просто давайте на него гиперссылку.
4) Привлекайте внимание пользователя правильно
Когда в описании надо привлечь внимание пользователя, используются следующие вводные слова – «Внимание!» (по-английски – Warning!), «Важно:» (по-английски — Important:) и «Примечание:» (по-английски – Note:).
Каждое из этих слов подразумевает свой уровень «важности».
Чтобы не напрягать пользователя напрасно, используйте каждый термин правильно:
- Используйте «Внимание!» (по-английски – Warning!), чтобы обозначить опасную ситуацию, которая, если ее не избежать, может привести к потере данных, повреждению комплектующих или любому другому урону.
- Используйте «Важно:» (по-английски — Important:), чтобы обозначить значительную и потенциально проблемную ситуацию, которая, однако, не может привести к физическому урону, повреждениям или потере данных.
- Используйте «Примечание:» (по-английски – Note:), чтобы предоставить любую дополнительную информацию, относящуюся к данному топику. Хоть такая вставка и отрывает пользователей от выполнения текущей задачи, но она может быть полезна.
Например:
Чтобы открыть конфигурацию виртуальной машины, нажмите Действия > Настроить.
Примечание: виртуальная машина должна быть выключена.
Используйте пометку «Примечание:» умеренно – если вставлять ее слишком часто, она забивает текст, и на нее перестают обращать внимание.
По возможности, вставляйте «Внимание!», «Важно:» и «Примечание:» в начале топика, чтобы пользователь узнал об этом перед тем, как начал выполнять какую-либо процедуру. Однако если информация относится только к какому-то конкретному шагу, вставляйте их после этого шага.
Пример:
Продолжение следует…
(в следующей части статьи мы подробнее разберем топики, которые описывают, как решить конкретную задачу)
Автор: MarinaTalyzina
