Принципы разработки пользовательской документации

Термины

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

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

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

Отдельным классом в технической документации выделяется пользовательская документация, которая даже пишется во время отдельного этапа (например, по ГОСТ 34).

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

Существует два вида пользователей. которые:

1) читают все инструкции и изучают всю инфографику по новой стиральной машине перед первым использованием;

2) сначала ломают стиральную машину, потом открывают гайд, чтобы найти номер сервисной службы.

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

Пользовательские документы называются по-разному, самые распространенные — туториал, хелп, инструкция, гайд, мануал и руководство.

Чем же они отличаются? Ничем!

Пожалуй, только ХЕЛП можно выделить в какую-то отдельную категорию, это короткая инструкция, так называемый «быстрый старт», который содержит базовые функции, возможности и советы для начала. Главное его отличие от полного руководства — он быстрее читается, дает базовое представление о продукте и особенно помогает при внедрении b2b продуктов.

Стандарты разработки

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

Постановка задачи для разработки документа

Для начала надо определиться, каким способ описания выбрать: от функций или от интерфейса.

Если вы будете описывать программное обеспечение «от интерфейса» — на выходе получите справочник с описанием функций и возможностей продукта.

Если вы выберете способ «от функций» — получите руководство пользователя с пошаговым решением пользовательских задач.

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

Самое важное для клиента — ответы на вопросы, как сделать то или иное полезное действие, а не исследовать бизнес-заморочки

Содержание документа

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

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

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

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

Структура документа

Глубина — вложенность документа: глава, раздел, подраздел, пункт, подпункт.

Сечение — количество элементов в каждом уровне вложенности, т.е. количество подразделов в разделе, пунктов — в подразделе, и т.д.

Идеальная структура получается в результате правильного баланса между глубиной и сечением: <= 4*9.

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

Стиль изложения

Хорошее изложение пользовательского документа держится на четырех основных правилах:

• используйте повелительное наклонение, второе лицо, множественное число, обезличенное обращение;
• используйте инфостиль;
• пишите грамотно;
• обогащайте текст рисунками, таблицами, примерами.

Повелительное наклонение

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

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

Избегайте изложения в первом лице, множественном числе — «мы нажимаем» – оно создает ненужное ощущение опеки.

Инфостиль

Вот как определяет инфостиль один из его авторов, Максим Ильяхов: «Информационный стиль — это не совсем стиль. Это приемы редактирования, которые помогают очистить текст от мусора, наполнить его полезной информацией и сделать читаемым. Текст в информационном стиле лаконичный, интересный и честный».

Следуйте правилам инфостиля при изложении текста инструкций:

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

Правило 1. Составляйте название так, чтобы оно четко отражало суть того, что надо сделать, вводите четкое название и используйте глаголы, а не существительные.

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

Правило 2. Удаляйте словесный мусор.

Убирайте из текста стоп-слова, которые удаляются без потери смысла. Простой — не значит примитивный. В тексте может быть сложная мысль, можно использовать термины и вводить сложные понятия, но не стоит одну и ту же мысль выражать сложнее.

Словесный мусор или стоп-слова можно условно разделить на несколько групп:

• вводные конструкции — наиболее простая группа стоп-слов, их легко найти в тексте, избавиться от них тоже довольно просто: «всем известно», «не секрет», «например», «кстати»;
  
  
• оценки — текст с оценками становится слабым, потому что у автора появляется ложное чувство проделанной работы. Чтобы оценка стала убедительной, её необходимо заменить или дополнить фактами;
  
  
• штампы — это популярные устойчивые словосочетания, смысл которых либо неясен, либо можно выразить одним словом;
  

  В целях улучшения качества обслуживания	Чтобы помогать вам быстрее и лучше
  Во избежание задержки платежа	Чтобы платеж не задержался
  Данное решение	Решение
  Просьба написать заявление	Напишите заявление
  Я являюсь сотрудником службы поддержки	Я сотрудник службы поддержки
  Было принято решение	Банк принял решение
  Проводятся работы по улучшению	Работаем над улучшением → Улучшаем
  Осуществлять проверку	Проверять
  Производить оплату	Оплачивать
  Надлежащим образом	Правильно
  Для подключения услуги	Чтобы подключить услугу
  Открытие нового счет	Открыть счет

• заумные слова — чем проще слова, тем легче читателю воспринимать текст;
  
  
• отглагольные существительные. Когда читатель знакомится с текстом, он рисует в голове картину. Если в тексте много действия, то это динамичная картина, за которой интересно наблюдать. Чаще всего действие выражается глаголом. Но иногда действие прячут, будто стесняются, скрывают его за существительным.
  
  
• деепричастные обороты усложняют чтение текста и создают дополнительную возможность ошибиться с запятыми или употреблением падежа;
  
  
• неопределённые слова — читателю не нужно знать точное число клиентов, ему нужна ориентировочная величина, чтобы составить общее впечатление.
  
  

Правило 3. Следите за своим профессиональным жаргоном, если без термина не обойтись — объясняйте его.

Правило 4. Разбивайте текст на списки или просто абзацы с подзаголовками и выделением.

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

Правило 5. Проверяйте текст на лаконичность на сайте glvrd.ru

Главред помогает очистить текст от словесного мусора и проверяет на соответствие информационному стилю.

Грамотность

Проверяйте орфограммы в справочнике Розенталя.

Используйте проверку правописания в Word.

Упрощайте предложения, если не уверены в пунктуации.

Читайте Пушкина по 10-12 страниц в день.

Соблюдайте некоторые простые правила, чтобы ваш текст не выглядел неграмотным или неуклюжим:

1) подлежащее и сказуемое ставьте рядом, не разделяйте их второстепенными членами;

2) точка — лучший знак препинания, много запятых в предложении — признак сложной конструкции;

3) не нанизывайте родительный падеж более 3 раз;

4) вместо «Для того чтобы» используйте «Чтобы», вместо «В случае если» - «Если»;

5) чтобы избежать частой ошибки ться/тся задавайте вопрос «что делает/что делать»;

6) «вы», «ваш», «вам» пишите со строчной в середине предложения., избегайте рекламно-подобострастной манеры «Вы». Вы — это множественное число, при обращении к одному человеку звучит уже достаточно почтительно (по сравнению с «ты») и не требует дополнительных украшений;

7) названия компаний и сервисов пишите так, как они сами себя называют на официальном сайте (перепроверяйте).

8) от нуля до девяти пишите словами. От 10 и дальше пишите цифрами;

9) никогда не используйте слово функционал, когда говорите о функциях. Слово «функционал» имеет несколько конкретных значений:

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

А функции платформы — это не функционал!

Обогащение текста

Обогащайте текст иллюстрациями по правилу: одна статья = как минимум одна иллюстрация. Если в статье нечего иллюстрировать - статья плохая, но и иллюстрировать каждый шаг не стоит. Большое количество скриншотов, в том числе отдельных кнопочек, мешает восприятию, портит вёрстку и требует постоянного контроля, если продукт регулярно обновляется.

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

Имейте в виду, что чем меньше выделений, тем лучше. Когда их много, текст «шумит». Шум создают даже кавычки, если используются слишком часто.

Примеры документации

support.google.com — справочный центр Google, пример составления базы данных для большого количества продуктов;

yandex.ru/support — Яндекс.Помощь, ещё один пример;

docs.microsoft.com — документация Microsoft c простой навигацией и обратной связью;

wiki.wargaming.net — документация Wargaming, пример удачного использования графических элементов и решения проблемы версионности;

help.loco2.com — отличный пример документации, в которой всё разложено по полочкам.