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

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


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

    Начало статьи можно почитать тут, а то, как проходит процесс документирования и локализации наших продуктов мы описывали ранее в этой статье.

    В этой части мы подробно разберем топики, из которых в основном состоит пользовательская документация (особенно User’s Guide) – а именно task-топики, в которых рассказывается, как решить конкретную задачу.

    image

    Сколько задач описать в топике – одну или несколько?

    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”), чтобы таким образом подготовить пользователя к терминам, которые будут далее использоваться в топике.

    image

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

    Не вставляйте вводную часть там, где это не надо

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

    Например:

    Запускайте приложения Mac через меню «Пуск»

    Откройте меню Windows «Пуск» и выполните одно из следующих действий:

    • Нажмите Все программы > Parallels Shared Applications и выберите нужное приложение.
    • Введите название приложения в поле поиска и выберите нужное приложение из предложенных вариантов.


    Не делайте вводную часть слишком длинной

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

    Если вводная часть получается слишком большой, надо упомянуть основное и дать ссылку на отдельный концептуальный (conceptual page) или справочный топик (reference page), в котором уже все будет подробно описано.

    Иногда, чтобы визуально облегчить чтение длинного текста в вводной части, можно использовать буллиты. Например:

    image

    Не рассказывайте в вводной части, как выполнить задачу

    Вводная часть не для этого. Что надо сделать, где и как — надо описывать уже потом, после вводной части.

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

    image

    Не описывайте результаты задачи в вводной части

    Это следует делать в заключительной части (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 близких и связанных действия в один шаг, как показано ниже:

    image

    Используйте буллиты для выделения непоследовательных действий

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

    Например:
    image

    Если в списке присутствуют названия графических элементов, выделяйте их для наглядности жирным шрифтом

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

    Как показано в этом примере:
    image

    Если текст в топике много раз ссылается на различные элементы интерфейса, возможно, стоит создать отдельный справочный топик, в котором эти элементы будут описаны.

    Особенно это будет полезно, если много топиков в гайде ссылаются на одни и те же элементы. В таком случае, в начале топика надо дать ссылку на справочный топик, в котором упомянутый элемент разъяснен.

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

    Заключительная часть (Outro)

    Outro – это заключительная информация, которая идет после пронумерованных шагов. Заключительную часть надо стараться делать покороче – используйте не более 3 параграфов, каждый из которых состоит максимум из 3 предложений.

    Используйте Outro, чтобы описать результаты или последствия перечисленных действий.

    Примером результата или последствий могут быть:

    • Информация о том, куда были установлены какие-нибудь файлы;

    • Появившееся сообщение, которое потребует от пользователя дополнительных действий;

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

    Например, заключительная часть топика о том, как заставить Parallels Access работать только по Wi-Fi, говорит следующее: «Если вы настроили Parallels Access работать только по Wi-Fi, а беспроводных сетей в данный момент не обнаружено, появится сообщение, которое спросит вас – не хотите ли подключиться по 3G?».

    В заключительной части топика можно описать альтернативный способ выполнения задачи

    Если альтернативный способ можно описать одним предложением – можно сделать это в заключительной части топика.

    В Outro можно дать больше информации, которая относится к текущей задаче

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

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

    image

    В Outro можно описать дополнительную информацию, которая понадобится только некоторым пользователям

    Например, в заключительной части топика про интеграцию виртуальных машин Windows в macOS можно написать следующее: «Если у вас MacBook Pro 2016 года выпуска или позже, то вы можете работать с некоторыми приложениями Windows, используя Touch Bar»


    Разбивайте длинные задачи на короткие этапы

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

    Ниже приведен пример из содержания Parallels Desktop User’s Guide. На скриншоте показана глава, в которой описываются различные способы установки Windows в виртуальную машину. И один из способов – как импортировать данные с удаленного компьютера – разбит на несколько топиков.

    image

    Продолжение следует…

    (в следующей части мы подробнее расскажем о концептуальных и справочных топиках и о топиках, которые помогают решить проблемы)
    Parallels
    108,00
    Мировой лидер на рынке межплатформенных решений
    Поделиться публикацией

    Комментарии 4

      +1
      hsto.org/webt/eu/mu/tu/eumutuftauqkp1panbo6xtanf7e.png

      Вы вводите определение «режим Coherence» которое стараетесь дальше использовать (тут же).

      Предположим я первый раз вижу вашу программу — ничего не знаю о режиме coherence а первый абзац этого листа я даже прочитал — но как обычно через строку, и ничего оттуда не усвоил…

      Дальше мне в тексте встречается это понятие «режим coherence». — и я не зная, что это дословным поиском по тексту пытаюсь найти определение… И тут выясняется — в вашем определении, эти слова даже рядом не стоят! Т.е. я найду, что угодно — но не описание, что же это за режим такой…

      Суть: Если вы вводите какое то понятие, посвящаете ему целый абзац текста, используете его в дальнейшем — заголовок абзаца должен называться в точности этим понятием — т.е. абзац должен быть назван «Режим coherence» и выделен красным текстом — а то что это «объединение windows blabla» — можно или оставить в названии абзаца мелким текстом черед дефис или перенести в суть определения (середину абзаца)… Таким образом у вас определение оказывается и в оглавлении и выделяется жирно красно при поиске. Либо на крайний случай это понятие должно быть как то выделено в тексте в месте где оно определяется — что бы оно хотя бы поиском как то однозначно находилось.
        0
        Не согласен с требованием выносить режим в заголовок абзаца, при этом теряется исходная идея task-топика, то есть подхода «от задачи». Режим же здесь — средство выполнения задачи, он вторичен. Другое дело, что определен он в самом деле не сильно явно — тут согласен. Если уж используется термин «режим Coherence» — так и определен он должен быть именно в таком виде.
        Ну и маленькая реплика от нормоконтроля: «Чтобы переключиться из режима „Окно“ в Coherence...» — всё же стоит использовать одинаковые подходы в именовании режимов — либо везде в кавычках, либо везде без них.
          0
          Что первично и что вторично в документации определяется совсем не этим. Если вы многократно ссылаетесь на определение а задачу описали лишь в одном месте — значит определение у вас важнее задачи в рамках структуры вами же написанного текста. Хотя тут еще вопрос. А нужно ли вообще вводить это определение? действительно ли оно что то экономит в объяснении — а не запутывает. Ключевая фраза объяснения определения — не сильно длиннее самого определения.

          А вообще — все это лишние знания… Любой нормальный человек способный к анализу текста, просто интуитивно напишет хорошую документацию, прочитав за свою жизнь «десять условных других хороших документаций»… а если способностей нет — то не напишет, сколько в него не долби, как они пишутся… Нужно просто в рамка проекта найти такого человека — и задача решена…
        0
        Спасибо большое за то, что делитесь своим опытом. Ваш подход тоже можно использовать. Термины также можно подробно описывать (и раскрывать) в справочных топиках или в словаре, о них будет отдельно рассказано в следующих частях «руководства».

        Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

        Самое читаемое