Пользовательская документация  —  не самая интересная тема для разработчиков. Однако важно убедиться, что продукт не причинит вреда пользователям  —  ни физически, ни в плане повреждения их собственности. Утрата данных, выход из строя оборудования и прочие проблемы могут привести к серьезным судебным претензиям. 

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

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

Определить целевую группу

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

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

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

  • Если аудитория состоит из людей старшего поколения, то используйте хорошо читаемый разборчивый шрифт. 
  • Если же она представлена разработчиками, то нет необходимости объяснять базовые шаги в ОС Windows. 
  • Если вы пишите для дислексиков, то делайте предложения короткими и используйте простые термины.

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

Понять, как будет использоваться продукт 

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

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

  • Функционально-ориентированное название главы: “Использование мастера экспорта”.
  • Задачно-ориентированное название главы: “Экспортирование данных проекта”.

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

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

В этом случае рекомендуется спросить себя следующее.

  • Что будут делать пользователи с продуктом?
  • Почему они его используют? Какова их цель?

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

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

Начните с инструкций

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

Инструктивная глава дает пользователю пошаговый алгоритм действий.

Советы по написанию инструктивных глав

Вот несколько советов, которые нужно учесть при написании инструктивных глав.

  • Начинайте название главы с существительного. Пример: “Экспортирование данных проекта”.
  • Структурируйте инструктивные главы в виде нумерованного списка. Каждый этап задачи должен представлять один пункт списка.
  • Инструктивная глава не должна превышать 11 шагов. Большее число шагов излишне ее удлинит, снизив удобство чтения. Если в итоге у вас получается длинная глава, то поделите ее на подразделы.
  • Описывайте шаги в императивной форме. Пример: чтобы экспортировать данные проекта, нажмите на значок “Экспорт”.
  • Не предоставляйте подробной информации о возможности продукта или о том, как он работает. Вместо этого сосредоточьтесь на выполняемых пользователем шагах. Главы с сопутствующей информацией относятся к следующему этапу руководства.

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

Пример инструктивной главы

Добавление сопутствующей информации

После написания инструкций спросите себя: “Что нужно знать пользователям (чего они еще не знают) для выполнения всех этих инструкций?”

Перед каждой инструктивной главой добавляйте концептуальные. Они будут объяснять особенность ПО, необходимую для выполнения инструкций. В примере “Экспортирование данных проекта” одна глава может быть посвящена мастеру экспорта и поддерживаемым форматам данных.

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

Советы по написанию сопутствующей информации

Вот несколько советов, актуальных при написании концептуальных глав.

  • Не добавляйте в заголовках описательные приставки типа “О…” или “Сведения о…”. Называйте только сам принцип или функцию, которую хотите описать. Почему? Когда вы ищете что-либо по теме в интернете, то не вводите “Сведения о затмении”. С большей вероятностью вы будете искать по запросу “Затмение”. Когда пользователи ищут принципиальную информацию, они действуют аналогично, например пишут запрос “Мастер экспорта”.
  • Добавляйте только такие концептуальные главы, которые помогут пользователям выполнить инструкцию. Вероятно, вы вложили немало усилий в разработку бэкенда, необходимого для работы конкретной функции. При этом сложности, связанные с ее реализацией, не должны отражаться в документации. Единственное исключение  —  когда пользователю нужно знать эти детали для выполнения инструкций. Перед написанием концептуальной главы всегда спрашивайте себя: “Зачем пользователю нужно это знать?”.
  • Связывайте описательные главы с соответствующими инструктивными и наоборот.

Пример главы с сопроводительной информацией

Добавление справки

Последний компонент  —  это справка. Справочные главы содержат информацию для поиска в виде таблиц. В этих таблицах вы описываете графический интерфейс пользователя (GUI) и API.

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

Советы по написанию справочной информации

  • Заголовок справочной главы должен совпадать с элементом GUI или описываемой в ней функцией, например “Диалоговое окно мастера экспорта”.
  • Обязательно называйте элементы GUI так же, как они названы в самом GUI. Пользователи зачастую копируют названия элементов и вставляют их в строку поиска.
  • Подумайте, какая информация поможет пользователю, ищущему конкретный элемент GUI. Возможно, он как-то связан с другими элементами GUI или ограничениями. Задокументируйте их в справочной главе.

Примеры справочных глав

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

Я не стал детально объяснять, почему рекомендую структурировать и писать руководства именно так. Моей целью было научить вас делать это максимально быстро. 

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

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

Помните, что мануалы мы читаем не ради удовольствия, а от необходимости.

Читайте также:

Читайте нас в Telegram, VK и Яндекс.Дзен

Перевод статьи Andreas D.: How To Write Manuals as a Developer

Предыдущая статьяКак автоматизировать сравнение датасетов с Terraform и BigQuery
Следующая статьяКомплексная разработка веб-приложений с помощью React и Node.js