Вредные советы: как правильно писать техническую документацию? Часть третья и последняя

Советы по грамотному написанию технической документации для пользователей.
Часть 3 (заключительная)

Заключение руководства нашего технического писателя Андрея Старовойтова, которое поможет сделать вашу пользовательскую документацию проще и понятнее.



На этот раз мы поподробнее рассмотрим:

• концептуальные топики (concept pages);
• справочные топики (reference pages);
• топики, в которых рассказывается, как решить какую-нибудь проблему (troubleshooting pages);
• где и как использовать скриншоты;
• а также дадим пару советов тем, кто пишет документацию на английском.

Предыдущие части: наш подход к документированию и локализации; советы по документированию часть 1 и часть 2.

Концептуальные топики (concept pages)

Такие топики нужны, чтобы предоставить пользователям дополнительную техническую информацию и тем самым не перегружать task-топик.

Обратите внимание, что в них должна быть именно дополнительная информация, но не способ решения задачи.

Концептуальные топики хорошо использовать для того, чтобы:

• рассказать, как работает тот или иной процесс;
• описать, какие новые фичи были добавлены в этой версии продукта;
• предоставить пользователю дополнительную информацию, которая поможет ему принять какое-либо решение;
• рассказать, что пользователь может делать в вашем приложении.

Например, в топике «О виртуальных машинах» (“About Virtual Machines”) может описываться, что это такое и как работает. Но в этом топике не должно быть инструкций, как создать виртуальную машину – это должно быть описано в task-топике.

Таким образом, опытный пользователь, читая task-топик, не будет жаловаться: «Зачем вы мне расписываете, что это такое, я и так знаю…». А тот, кто не знает, увидит ссылку на концептуальный топик и прочитает.

Обычно заголовки концептуальных топиков начинаются с:

• «О (чем-то)» (“About Virtual Machines”);
• «Что такое …?» (“What is a Virtual Machine?”);
• «Как работает (что-то)?» (“How a Virtual Machine Works?”);
• «Подробнее о чем-то» (“Understanding Virtual Machine Basics”) и т.д.

Вот пример концептуального топика из английской документации:



Справочные топики (reference pages):

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

Хорошими примерами таких топиков могут служить:

• «Словарь» (“Glossary”) в конце гайда;
• топик, в котором вы описываете, какие элементы доступны в меню и что они делают, какие быстрые сочетания клавиш можно использовать при работе с программой, какие иконки доступны на таскбаре и т.д.

Вот пример топика, в котором описаны иконки графического интерфейса:



Топики, которые описывают, как решить какую-нибудь проблему (troubleshooting pages)


Такие топики помогают пользователю преодолеть препятствие или решить какую-нибудь проблему. У troubleshooting-топиков могут быть следующие сценарии:

• У пользователя проблема, и он хочет ее решить. Например, «Мое USB-устройство не работает в виртуальной машине» (“My USB Device Doesn’t Work in a Virtual Machine”).
• Пользователь попробовал что-то сделать и у него не получилось. Например, «Я не могу активировать Parallels Desktop» (“I Can’t Activate Parallels Desktop”).
• Есть какое-то условие или состояние, которое пользователь хочет изменить. Например, «Windows работает медленно» (“Windows Seems Slow”).

Что является и не является troubleshooting’ом:

Если пользователь хочет сделать что-то, но не знает как – это надо описывать не в troubleshooting, а task-топике.

Troubleshooting подразумевает, что пользователь попытался сделать что-то (по инструкции task-топика), но возникла какая-то проблема, и пользователь не знает, как ее решить.

Например, топик, который описывает, как использовать внешний диск в гостевой операционной системе — это task-топик.

А топик, который описывает возможные проблемы – «Не могу подключить внешний диск» (“I’m having problems connecting a hard disk”) – это troubleshooting-топик. Его содержание подразумевает, что пользователь следовал инструкциям, но по какой-то причине у него не получилось.

Если вы пишете task-топик, и какой-то шаг в инструкции может вызвать небольшие затруднения, допускается описать это в том же шаге или топике. Для небольших затруднений необязательно писать отдельный troubleshooting-топик.

Например, в конце топика, который описывает, как изменять быстрые сочетания клавиш, можно добавить: «некоторые шорткаты нельзя изменить или удалить» (“Some key combinations can’t be edited or deleted”).

Разделы Troubleshooting-топика

Обычно troubleshooting-топики имеют структуру схожую с task-топиками.

Они состоят из:

• Заголовка (“title”)
• Вводной части (“intro”)
• Вводной фразы, после которой начинаются пронумерованные шаги или необходимая информация (“step heading”)
• Информации, которая нужна для того, чтобы решить проблему (“steps to solution”)
• Заключительной части (“outro”)

Заголовок (page title)

Хорошо, когда заголовок troubleshooting-топика выражает проблему пользователя от первого лица. Например:

• «Я не могу активировать Parallels Desktop» (“I Can’t Activate Parallels Desktop”)
• «Windows работает медленно» (“Windows Seems Slow”)
• «Появляется сообщение «У вас нет виртуальных машин»» (“A Message Says ‘No Virtual Machines Detected’”)

Если вы пишете документацию на английском, в заголовке надо использовать title-style капитализацию (про капитализацию смотрите подробнее в конце статьи):

Правильно: My USB Device Isn’t Working

Неправильно: My USB device isn’t working

Введение (intro)

Сразу после заголовка предоставьте пользователям информацию, которую им надо знать прежде всего.

Например:

• Объясните наиболее вероятную причину проблемы. Если причин может быть много, опишите все возможные.
• Иногда можно в общих словах описать, что нужно делать, чтобы решить проблему. Именно в общих – детальные инструкции надо давать в steps to solution.

Вводная фраза (step heading)

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

Если решение проблемы представляет собой набор последовательных действий:

В таких случаях вводную фразу нужно делать по тем же принципам, что и для task-топиков (см. 2-ую часть советов), а именно – используйте те же слова, что и в формулировке задачи.

Например, вы пишите troubleshooting-топик, в котором объясняете, почему пользователь не может открыть конфигурацию виртуальной машины (пункт меню выделен серым и неактивен):

Заголовок: «Я не могу открыть настройки виртуальной машины» (“I Can’t Open the Virtual Machine Settings”)

Введение: «Если вы не можете открыть настройки виртуальной машины (пункт меню выделен серым), то наиболее вероятная причина в том, что виртуальная машина не выключена.»

Далее вводная фраза: «Чтобы открыть настройки виртуальной машины:» (в этой фразу используются те же слова, что и в формулировке задачи, которую надо выполнить)

А дальше уже шаги – 1) Убедитесь что машина выключена. Если она работает, нажмите там-то и там-то. 2) Потом сделайте то-то.

Если у проблемы несколько решений:

В таких случаях, вводная фраза должна содержать слова:

— «попробуйте эти способы» (“try these solutions”),
— «попробуйте предпринять следующее» (“try the following”),
— «убедитесь, что» (“make sure that”) и пр.

Вот несколько примеров из английской документации:

Page Title: I Can’t Activate Parallels Desktop
Task Covers: A list of things to check
Step Heading: If you’re having trouble activating Parallels Desktop, make sure that…

Page Title: Windows Seems Slow
Task Covers: A list of things to try
Step Heading: If Windows performance seems slow, try the following…

Page Title: A Message Says “No Macs Connected”
Task Covers: Several things to check or try
Step Heading: If you don’t see your Mac in the list of Macs

Информация, необходимая для решения проблемы (steps to solution)

Этот раздел включает все то, что пользователю надо знать и/или предпринять.

Если решений несколько:
В таких случаях описывайте каждый способ, используя буллиты (об этом более подробно можно почитать во второй части советов). Если какой-то способ сложный, и вы его уже детально описали в другом топике, просто дайте ссылку.

Если то, что надо сделать, уже описано где-то в другом топике:
Просто дайте ссылку на этот топик.

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

Заключение (outro)

В заключении можно предоставить дополнительную информацию, относящуюся к выполнению задачи или возможным вариантам решения проблемы. Более подробную информацию об использовании outro можно прочитать во второй части советов.

Использование графики (скриншоты, диаграммы, схемы и т. д.)

Скриншоты и схемы могут помочь пользователям значительно лучше понять то, что написано в топике.

Когда использовать графику:

Под каждым шагом скриншот вставлять не надо – пользователь просто не будет знать, куда смотреть, постоянно сравнивая экран и скриншот.

Скриншоты надо вставлять тогда, когда они существенно помогут понять, что написано в инструкции.

Например:

• Когда надо показать кнопку или иконку, которая в гуе не имеет названия, или не сразу бросается в глаза, или на скрине есть несколько похожих;
• Когда надо предоставить контекст для выполнения задачи или понятное визуальное объяснение, как и что будет выглядеть в итоге;
• Если скриншот позволит быстро понять или объяснить что-то, что потребует слишком длинное и сложное объяснение словами.

Где и как размещать графику:

Ниже представлены несколько рекомендаций, где и как размещать графику на странице.

1) Если скриншот отражает концептуальную информацию или результат выполнения задачи, можно вставить его в или после intro.

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



2) Если скриншот относится к какому-то конкретному шагу в инструкции, вставляйте его после или внутри этого шага:



Если вам надо вставить скриншот кнопки, иконки или другого элемента интерфейса, надо вставлять его после названия этого элемента:



Не используйте графику для иллюстрации очевидных вещей

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

• Меню
• Иконки, кнопки и табы, у которых есть название
• Все остальное, что можно легко и доступно описать словами.

Дополнительные советы для тех, кто пишет документацию на английском:


1) How to capitalize titles:

capitalization Three styles of capitalization are available: sentence style, title style, and all caps.

• Sentence-style capitalization: This line provides an example of sentence-style capitalization.
• Title-style capitalization: This Line Provides an Example of Title-Style Capitalization.
• All caps: THIS LINE PROVIDES AN EXAMPLE OF ALL CAPS.

Don’t use all caps for emphasis.

capitalization (sentence style): When you use sentence-style capitalization, capitalize the first letter of the first word, as well as the first letter of any proper nouns and proper adjectives.
capitalization (title style): Use title-style capitalization for book titles, part titles, chapter titles, and section titles (text heads).

Follow these rules when you use title-style capitalization. Capitalize every word except:

• Articles (a, an, the), unless an article is the first word or follows a colon
• Coordinating conjunctions (and, but, or, nor, for, yet, and so)
• The word to in infinitives (How to Connect Your Printer)
• The word as, regardless of the part of speech
• Words that always begin with a lowercase letter, such as iPhone and iPad.
• Prepositions of four letters or fewer (at, by, for, from, in, into, of, off, on, onto, out, over, to, up, and with), except when the word is part of a verb phrase. For example:
  
  Start Up the ComputerLog
  In to the ServerGet
  Started with Parallels Desktop

Capitalize:

• The first and last word, regardless of the part of speech:
For Linux Users

What Parallels Tools Are For

• The second word in a hyphenated compound:

Correct: High-Level Events, 32-Bit Addressing
Incorrect: High-level Events, 32-bit Addressing
Exceptions: Built-in, Plug-in

• The words Are, If, Is, It, Than, That, and This

2) How to use the word “click”:

click Use click to describe the act of positioning the pointer on an object onscreen and briefly pressing and releasing the mouse button. Don't use click on. Because most users know what clicking is, you need to define it only in documentation designed for beginning users, such as tutorials.
Correct: Click Mac if you want to use the USB device with Mac OS X.

Incorrect: Point to Mac and click it if you want to use the USB device in Mac OS X.
click on Don't use; use click.

3) Email or e-mail?

Use email. Don't use e-mail.

4) If or whether?

Use if to express a condition. Use whether to express alternatives.
Correct: Check whether Parallels Tools have been installed.
Incorrect: Check if Parallels Tools have been installed.
Correct: Click Mac if you want to use the USB device with Mac OS X.

5) How to use product names:

Follow the capitalization style on the product's packaging. Use the full product name for its first occurrence within a section of text (for example, a chapter). Thereafter, when applicable use a shortened version of the product name.

For example: Parallels Desktop 14 for Mac: On first occurrence within a section of text, use Parallels Desktop 14 for Mac.

On subsequent occurrences, use Parallels Desktop.

Заключение

В этих 3 частях руководства мы постарались собрать воедино, обобщить и структурировать советы, которые помогут сделать вашу документацию проще и понятнее.

Мы не настаиваем, что писать надо именно так – подходов к документированию и приемов много. Смотрите по обстановке и используйте те, которые вам подходят.

Спасибо большое за внимание и интерес!