Вредные советы: как правильно писать техническую документацию? Часть вторая +11
Управление проектами, Управление разработкой, IT-компании, Блог компании Parallels
Рекомендация: подборка платных и бесплатных курсов создания сайтов - https://katalog-kursov.ru/
Советы по грамотному написанию технической документации для пользователей.
Часть 2
Продолжение руководства нашего технического писателя Андрея Старовойтова, которое поможет сделать вашу пользовательскую документацию проще и понятнее.
Начало статьи можно почитать тут, а то, как проходит процесс документирования и локализации наших продуктов мы описывали ранее в этой статье.
В этой части мы подробно разберем топики, из которых в основном состоит пользовательская документация (особенно User’s Guide) – а именно task-топики, в которых рассказывается, как решить конкретную задачу.
Сколько задач описать в топике – одну или несколько?
Task-топик может описывать как одну задачу — «Запустите Windows-приложение» (“Launch a Windows Application”), так и несколько связанных между собой задач. Например, топик «Оптимизируйте производительность» (“Optimize Performance”) может состоять из следующих разделов: «Экономьте место на диске автоматически» (“Automatically Conserve Disk Space”) и «Настройте MacBook на лучшую производительность или на экономию заряда» (“Optimize Your MacBook for Longer Battery Life or Higher Performance”).
Надо стараться писать task-топики по принципу: один топик – одна задача. Правда, тут есть исключение – если у вас есть две противоположные по действию задачи, то их стоит описать в одном топике. Например, если вам надо описать, как переключить виртуальную машину в полноэкранный режим и как из него потом выйти – это надо сделать в рамках одного топика.
Если же вам надо описать несколько связанных между собой задач, то это тоже можно сделать в одном топике при условии, что их описание не будет длинным.
Разделы task-топиков
Task-топики состоят из:
- Заголовка
- Вводной части (по-английски “intro”)
- Фразы, которая подводит к описанию того, что же конкретно надо сделать пользователю (по-английски “step heading”)
- Пронумерованных или начинающихся с крупной точки шагов (по-английски “numbered or bulleted steps”)
- Заключительной части (по-английски “outro”)
Иногда бывает, что task-топик содержит не все вышеперечисленные разделы – например, нет необходимости вставлять Intro или Outro. Далее мы подробнее остановимся на каждом разделе топика.
Заголовок
Надо стараться делать такие заголовки, чтобы пользователь сразу понимал, о чем будет написано в топике.
Делайте заголовки емкими, но в то же время не слишком длинным. Длинные заголовки могут не полностью отображаться в некоторых браузерах или Apple Help Viewer.
При написании заголовка используйте повелительное наклонение («Делайте то-то»)
Например, «
Настройте принтер через Bonjour» (“Set Up a Printer Using Bonjour”).
Не используйте императив в названиях топиков, которые не описывают как решить какую-то задачу.
В названии топика используйте понятные пользователю слова, не концентрируйтесь на элементах интерфейса.
Пользователю не хочется разбираться в фичах, терминах, элементах интерфейса итд — ему надо решить свою конкретную задачу. Поэтому в названии топика старайтесь использовать те слова, которые употребил бы сам пользователь. Например, если назвать топик «
Подготовьте Mac к использованию Windows приложений» (“Set Up Your Mac to Use Windows Applications”), то это будет намного понятнее для пользователя, чем топик «
О виртуальных машинах» (“About Virtual Machines”).
Старайтесь формулировать цель так, как это, вероятно, сделал бы сам пользователь. Например, вместо «
Начните удаленную сессию» (“Start a Remote Session”) — лучше назовите топик «
Начните работать с Windows удаленно» (“Start Controlling Windows Remotely”).
Если нужно использовать технически сложные термины или названия интерфейса, то это лучше делать не в заголовке, а в вводной части топика.
Если вы пишете документацию на английском, слова в заголовке должны начинаться с большой буквы
Правильно: Set Up Your Mac to Use Windows Applications
Неправильно: Set up your Mac to use Windows applications
(более подробно капитализацию заголовка мы разберем в следующей части руководства).
Вводная часть (Intro)
В вводной части, которая идет сразу после заголовка, следует писать то, что пользователю необходимо знать перед тем, как он начнет выполнять задачу.
Вводная часть может содержать:
- Дополнительную общую информацию: что пользователь может сделать.
- Мотивацию: зачем пользователю может понадобиться выполнить то или иное действие. Вот пример вводной части, которая описывает, почему вам может понадобиться скачать и использовать готовые виртуальные машины:
Используйте готовые виртуальные машины
Если у вас нет времени на создание новой виртуальной машины с необходимой конфигурацией, вы можете скачать готовую виртуальную машину с предварительно настроенной конфигурацией.
- Предупреждения (Warnings) о любой возможной порче оборудования, программного обеспечения, или потере данных, которые могут произойти, пока пользователь выполняет то или иной действие.
- Важную информацию (Important) о потенциальных проблемах или затруднениях, которые хоть и не ведут к повреждению здоровья, оборудования или потере данных, но могут возникнуть в процессе выполнения задачи.
- Объяснение: что означает тот или иной термин или как работает какая-нибудь фича.
Например, если пользователь Parallels Desktop хочет работать с macOS и Windows одновременно, как если бы это была одна операционная система, то в вводной части можно рассказать о «режиме когеренции» (“Coherence mode”), чтобы таким образом подготовить пользователя к терминам, которые будут далее использоваться в топике.
- Информацию о дополнительных условиях: например, в топике, который описывает как подключить принтер через Bonjour, вводная часть может информировать о том, какие версии Windows поддерживают Bonjour.
- Условия, необходимые для выполнения текущей задачи: если перед тем, как приступить к выполнению задачи, описанной в топике, пользователю надо сделать или проверить что-то еще, то об этом надо упомянуть в вводной части. И хорошо бы еще дать ссылки на топики, где это описано, чтобы пользователь смог быстро найти и прочитать.
Не вставляйте вводную часть там, где это не надо
Хоть вводная часть и предоставляет дополнительную полезную информацию, но иногда все понятно из самого заголовка. В таких случаях не надо придумывать вводный текст, лишь бы он был.
Например:
Запускайте приложения Mac через меню «Пуск»
Откройте меню Windows «Пуск» и выполните одно из следующих действий:
- Нажмите Все программы > Parallels Shared Applications и выберите нужное приложение.
- Введите название приложения в поле поиска и выберите нужное приложение из предложенных вариантов.
Не делайте вводную часть слишком длинной
Слишком длинная вводная часть напрягает пользователя. В таких случаях юзеры часто ее пропускают и переходят сразу к списку конкретных шагов.
Если вводная часть получается слишком большой, надо упомянуть основное и дать ссылку на отдельный концептуальный (conceptual page) или справочный топик (reference page), в котором уже все будет подробно описано.
Иногда, чтобы визуально облегчить чтение длинного текста в вводной части, можно использовать буллиты. Например:
Не рассказывайте в вводной части, как выполнить задачу
Вводная часть не для этого. Что надо сделать, где и как — надо описывать уже потом, после вводной части.
Однако, в редких случаях может потребоваться рассказать пользователям, что им потребуется, чтобы выполнить задачу. В приведенном ниже примере вводная часть говорит юзерам, что им необходимо для выполнения задачи, описанной в топике.
Не описывайте результаты задачи в вводной части
Это следует делать в заключительной части (
Outro).
Фраза перед инструкциями (Step Heading)
После Intro необходимо вставить «вводную» фразу (по-английски – “step heading”), которая подводит пользователя к инструкциям: что же конкретно надо сделать, чтобы добиться того или иного результата.
Например, в Intro мы пишем: «
Если у вас есть установочный диск и ключ активации, вы можете использовать их, чтобы установить Windows в виртуальную машину.»
После Intro идет step heading: «
Чтобы установить Windows:»
И далее сами шаги:
1) Кликните тут.
2) Выберете это.
3) И так далее…
Обратите внимание: если в топике нет Intro, то step heading вставлять необязательно.
Если в топике описываются последовательные шаги, то step heading должен выглядеть как «
Чтобы сделать что-то:» (“To do X:”).
Например: «
Чтобы запустить Windows:» (“To start Windows:”) или «
Чтобы переключиться в полноэкранный режим:» (“To switch to Full Screen mode:”).
Не забывайте в конце ставить двоеточие
Если в заголовке используются понятные пользователю слова, а в инструкциях вам приходится использовать сложные технические термины или названия элементов интерфейса, то можно сделать следующее: в вводной части вы объясняете, что означает термин, а в step heading уже его активно используете.
Например:
1) делаем заголовок попонятнее для пользователя:
«Запускайте Windows во весь экран» (“Set Windows to Take Up the Whole Screen”)
2) Далее в Intro представляем термин
«полноэкранный режим» (“Full Screen mode”).
3) После этого в step heading уже можно использовать термин, не опасаясь, что он будет непонятен пользователю:
«Чтобы войти в полноэкранный режим:» (“To enter Full Screen:”)
Если описанные в топике шаги представляют собой не последовательность действий, а несколько способов достижения цели, то step heading надо делать следующим образом:
«Вот несколько способов, как сделать что-то:» (“Here are ways to do X:”) или «
Чтобы сделать то-то, выполните одно из следующих действий:» (“To do X, do one of the following:”).
Например, «
Вот несколько способов, как выключить Windows:» (“Here are ways to shut down Windows:”) или «
Чтобы подключить принтер, выполните одно из следующих действий:» (“To connect a printer, do one of the following:”).
При создании step heading, нужно использовать те слова, которые отражают задачу, описанную в task топике. Вот несколько примеров на английском языке:
Page Title: Install Windows from an Installation Disc.
Task Covers: Installing Windows using an installation disc.
Step Heading: To install Windows.
Page Title: Adjust Coherence Settings.
Task Covers: Customizing how Windows appears and behaves in Coherence mode.
Step Heading: To customize Coherence mode.
Page Title: Set Windows to Take Up the Whole Screen
Task Covers: Entering full screen mode.
Step Heading: To enter Full Screen mode, do one of the following:
Пронумерованные шаги
Все топики, в которых описано, как выполнить ту или иную задачу, содержат инструкции, что надо делать. Эти действия в тексте обычно или пронумерованы (если это серия из последовательных шагов) или выделены буллитами (если предлагается выбрать что-то одно из списка на свое усмотрение).
Делайте список необходимых шагов как можно короче
Выберите и опишите самый простой и быстрый способ выполнить действие. Альтернативные способы можно описать в заключительной части (Outro) или в другом task-топике. Не заставляйте пользователя читать инструкцию из 4 шагов, если все то же самое можно выполнить, нажав на одну кнопку.
Если самый простой способ – это выполнить действие через тулбар, опишите этот вариант. Если панель инструментов можно настроить по своему вкусу, и у вас есть сомнения, вдруг у пользователя конфигурация тулбара отличается от описанной в топике, опишите все так, как делается при настройках по умолчанию. Как показывает практика, большинство обычных пользователей редко меняют «заводские» настройки.
Если надо описать несколько способов, как выполнить действие, в одном топике:
Если во многих task-топиках вашей книги повторяется некое действие, которое можно выполнить разными способами (скажем, через меню или панель инструментов), выберите один способ и упоминайте его последовательно в каждом task-топике.
Если же есть простой и короткий альтернативный способ, и вы непременно хотите о нем рассказать, можно сделать это в том же шаге.
Например: «
Чтобы открыть настройки виртуальной машины, нажмите Действия > Настройки или кликните иконку Настроить в правом верхнем углу» (“To open the virtual machine configuration, choose Actions > Configure or click the Configure icon in the top right corner.”).
Последовательно нумеруйте шаги, которые надо выполнить
Чтобы не раздувать описание и не выделять очень короткие инструкции в отдельные шаги (типа «Нажмите OK»), можно комбинировать 2 близких и связанных действия в один шаг, как показано ниже:
Используйте буллиты для выделения непоследовательных действий
Иногда пользователю предлагается несколько способов на выбор, как добиться цели. В таких случаях, предложенные варианты выделяют буллитами.
Например:
Если в списке присутствуют названия графических элементов, выделяйте их для наглядности жирным шрифтом
Если в действии, которое надо выполнить пользователю, перечисляется ряд элементов графического интерфейса (элементы меню, галки и т. д.), начинайте каждую опцию с новой строки, выделяя название элемента жирным шрифтом. После выделенного жирным элемента ставьте двоеточие и далее обычным текстом поясняющее описание.
Как показано в этом примере:
Если текст в топике много раз ссылается на различные элементы интерфейса, возможно, стоит создать отдельный справочный топик, в котором эти элементы будут описаны.
Особенно это будет полезно, если много топиков в гайде ссылаются на одни и те же элементы. В таком случае, в начале топика надо дать ссылку на справочный топик, в котором упомянутый элемент разъяснен.
Если далее по тексту будет снова упоминаться этот элемент, уже не надо давать на него ссылку – достаточно одной в начале. Когда в топике очень много ссылок, это может затруднять восприятие и понимание написанного.
Заключительная часть (Outro)
Outro – это заключительная информация, которая идет после пронумерованных шагов. Заключительную часть надо стараться делать покороче – используйте не более 3 параграфов, каждый из которых состоит максимум из 3 предложений.
Используйте Outro, чтобы описать результаты или последствия перечисленных действий.
Примером результата или последствий могут быть:
• Информация о том, куда были установлены какие-нибудь файлы;
• Появившееся сообщение, которое потребует от пользователя дополнительных действий;
• Настройки, которые пользователю надо будет переключить после того, как описанные действия были выполнены.
Например, заключительная часть топика о том, как заставить Parallels Access работать только по Wi-Fi, говорит следующее: «
Если вы настроили Parallels Access работать только по Wi-Fi, а беспроводных сетей в данный момент не обнаружено, появится сообщение, которое спросит вас – не хотите ли подключиться по 3G?».
В заключительной части топика можно описать альтернативный способ выполнения задачи
Если альтернативный способ можно описать одним предложением – можно сделать это в заключительной части топика.
В Outro можно дать больше информации, которая относится к текущей задаче
Такая информация может проинформировать пользователей о том, что еще они могут сделать после выполнения описанной задачи.
В следующем примере, топик описывает, как найти какой-нибудь файл из виртуальной машины в macOS Finder’е. А в заключительной части топика описывается, что еще пользователь может сделать с файлом, после того как файл найден.
В Outro можно описать дополнительную информацию, которая понадобится только некоторым пользователям
Например, в заключительной части топика про интеграцию виртуальных машин Windows в macOS можно написать следующее:
«Если у вас MacBook Pro 2016 года выпуска или позже, то вы можете работать с некоторыми приложениями Windows, используя Touch Bar»
Разбивайте длинные задачи на короткие этапы
В основном, task-топики получаются короткими и умещаются на одной странице. Однако, если описывается какая-то сложная и очень длинная задача, которую можно разделить на этапы, стадии и процедуры, стоит логически разделить информацию и описать каждый этап в отдельном топике, чтобы описание выглядело проще, лучше читалось и понималось.
Ниже приведен пример из содержания Parallels Desktop User’s Guide. На скриншоте показана глава, в которой описываются различные способы установки Windows в виртуальную машину. И один из способов – как импортировать данные с удаленного компьютера – разбит на несколько топиков.
Продолжение следует…
(в следующей части мы подробнее расскажем о концептуальных и справочных топиках и о топиках, которые помогают решить проблемы)
К сожалению, не доступен сервер mySQL