Как бы ни старался UX-дизайнер, не сможет человек с улицы разобраться в интерфейсе управления космическим кораблём без подсказки. И даже не с улицы. Просто потому, что ракета большая и настроек много.
Мы делаем продукты попроще софта для ракет, но всё равно технически сложные. Очень стараемся, чтобы интерфейсы новых версий были простыми, но осознаём — всегда найдётся пользователь, который что-нибудь не поймёт и пойдёт в документацию. Поэтому дока должна быть, а чтобы не портить впечатление о продукте, она должна быть полезной и удобной.
У нас шесть продуктов, документацию к которым с самого основания компании писали разработчики. Уже полгода мы переписываем старые и пишем новые статьи. Под катом — 50 вопросов, которые помогают нам делать это хорошо. Но для начала немного вводных.
Почему документация важна, и кто должен её делать
Сделать хорошую доку сложно. Где-то над ней работает огромный отдел аналитиков, писателей и редакторов, а где-то доку пишут разработчики (сделал — описал).
У нас два технических писателя на шесть продуктов с несколькими версиями. Этого мало, поэтому над докой работают продакт-менеджеры, тестировщики, первая линия поддержки и маркетинг. Они не пишут статьи, но помогают понять продукт и задачи клиента, выбрать тему и собрать информацию, проверить содержание и оформление готовой статьи. Вместе мы делаем доку лучше.
Если у вас небольшой отдел техписателей, привлекайте сотрудников других отделов. Если они не заинтересованы, приводите аргументы из списка ниже. Первый поддержке, второй и третий маркетингу и продактам. Итак, почему документация важна?
- Фактор поддержки. Первая и самая очевидная из причин. Если документация хорошая, бо́льшая часть клиентов решит вопрос, не обращаясь в поддержку. Оставшимся саппорт кинет ссылку на инструкцию или быстро пройдётся по ней сам. Полную документацию можно использовать для создания чат ботов. Всё это сокращает время ответа клиентам, повышает их удовлетворённость, а также снижает затраты на поддержку.
- Фактор выбора. Документация влияет на выбор клиента наравне с ценой, удобством, функциональностью. Это подтверждают наши исследования и обратная связь пользователей ISPmanager и DCImanager. В этом ключе дока перестаёт быть необходимостью поддержки, а становится конкурентным преимуществом, частью маркетинга.
- Фактор лояльности. Если клиент ушёл, не разобравшись в доке на старте или в процессе, — это проблема. Привлечение клиента стоит слишком дорого, чтобы терять его из-за плохих статей.
Как сделать хорошую документацию
Определить цель. Это самая боль. Описать фичу просто ради описания или прокомментировать интерфейс — это не цель. Цель — это всегда полезное действие. Что должен знать и уметь пользователь, админ или разработчик после прочтения статьи? Например, создать сайт и привязать к нему домен, выпустить SSL-сертификат, настроить бэкапы и пр. То есть решить свою задачу.
Знать аудиторию. Мы делим клиентов на пользователей, администраторов и разработчиков. Но этого недостаточно для создания полезных текстов. Чтобы быстро понять аудиторию, можно сходить к UX и продакту, изучить запросы в поддержку и их ответы на нужную тему, послушать звонки в первую линию, посмотреть сайт и блог (маркетинг тоже пишет нужные вещи). И только после этого начинать писать.
Проверять, редактировать и снова проверять. Техписатели должны делать первичную проверку. После неё ещё одну. Затем к проверке стоит подключить поддержку, маркетинг и другие отделы. Потом нужно свериться с руководством по стилю и оформлению — редполитикой. Кто-то со стороны или другой техписатель пусть делает финальную вычитку. Если у вас есть редактор, тогда этот этап на себя возьмёт он.
Редполитика оговаривает стиль изложения (формальный или неформальный), вёрстку и дизайн (скриншоты, их размеры, стили таблиц, списки), а также спорные вопросы (е или ё, написание терминов). Если у вас ещё нет такого документа, обязательно сделайте, он сокращает время и наводит порядок. Для вдохновения и понимания посмотрите доклад с конференции Яндекса и примеры руководств IBM или Mailchimp.
Распространять статью после публикации. Если документация написана, скорее всего, это кому-нибудь нужно. Покажите её свету и используйте по максимуму: переведите, сошлитесь в продукте, отдайте маркетингу, поддержке. Не пишите в стол.
50 вопросов для работы над докой
Работая над документацией, мы повторяли одни и те же ошибки. Тратили на проверку статей слишком много времени, а гайд, который казался изначально панацеей, не помогал, потому что проблема была в подходе и содержании. Чтобы техписатели могли довести статью до ума сами и быстро, мы собрали в один список все вопросы, которые постоянно задавали (или забывали задать) им. Используйте, если тоже пишете доку.
Цели
- Для кого я пишу статью? Кто будущий читатель: пользователь, администратор, разработчик?
- Какие задачи стоят перед ним (jobs to be done)? Есть ли описание персоны?
- Какой уровень подготовки этого пользователя? Что он уже знает? Что для него неочевидно?
- Как можно объяснить это начинающему пользователю и при этом не злить продвинутого объяснением элементарных вещей?
- Что ещё нужно объяснить пользователю, чтобы он понял основное содержание статьи?
- В какой раздел документации подойдёт эта статья?
- Эту статью или её часть надо продублировать в других разделах?
- На какие статьи нужно ссылаться?
- Может быть, эту статью следует сопроводить видеоинструкцией?
Источники информации
- У текущих пользователей есть проблемы, связанные с темой статьи?
- Как сейчас поддержка объясняет, что надо сделать?
- Отдел маркетинга писал на эту тему статьи и новости в блог? Можно ли у них «подсмотреть» формулировки, структуру и др.?
- Есть ли посвящённые этой теме разделы на сайте?
- Что в сценарий закладывал UX и продакт-менеджер? Почему сделал это так?
- Как этот вопрос описан у конкурентов?
- В каких сферах ещё можно посмотреть лучшие практики?
Проверка содержания
- Удалось ли достигнуть цели статьи?
- Всё ли будет понятно более продвинутому пользователю?
- Всё ли будет понятно начинающему пользователю?
- Всё логично и последовательно? Нет «скачков» и пропастей?
- Последовательность действий верна? Сможет ли пользователь достичь цели, следуя только этой инструкции?
- Мы учли все кейсы/пути пользователя?
- Статья вписывается в выбранный раздел?
Проверка вёрстки
- Есть ли нечитабельные простыни текста? Можно ли заменить схемой?
- Есть ли длинные абзацы?
- Есть ли слишком короткие абзацы?
- Есть ли слишком длинные списки?
- Есть ли слишком вложенные сложные для восприятия списки (те, в которых больше двух-трёх уровней)?
- Изображений достаточно?
- Изображений не слишком много? Не иллюстрируем ли мы слишком очевидные шаги?
- Если есть схемы, они понятны?
- Таблицы не сложны для восприятия?
- Страница в целом смотрится хорошо?
Литературное редактирование
- Всё оформлено по гайду?
- Соответствует ли стиль остальной документации?
- Есть предложения, которые можно упростить?
- Есть сложные термины, которые требуют пояснений?
- Есть канцеляризмы?
- Есть повторы?
- Ничего не режет слух?
Финальная вычитка
- Нет ли опечаток, ошибок в правописании и пунктуации?
- С переносами, абзацами и разделами всё в порядке?
- Все изображения подписаны?
- Элементы интерфейса названы правильно?
- Везде ли стоят ссылки? Они работают и ведут куда надо?
Сразу после публикации
- В статье есть разделы, которые «подтягиваются» в другие статьи? Они оформлены макросами, чтобы изменения в одной статье автоматически применялись к другим?
- На эту статью надо сослаться из других разделов? Если да, то из каких?
- Надо добавить в продукт быструю ссылку на эту статью?
- Надо ли отправить ссылку поддержке, маркетингу или другим отделам?
- Надо ли отдать статью на перевод?
Этот список можно распечатать и положить на рабочий стол или повесить на стену. Или превратить в чек-лист. Часть вопросов можно вынести в бизнес-процесс. Наш, например, зафиксирован в общем процессе разработки в YouTrack. Задача по документации проходит по разным этапам и отделам, без написанной документации нельзя отдавать фичу в релиз.
