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

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

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

Почему документация важна, и кто должен её делать

Сделать хорошую доку сложно. Где-то над ней работает огромный отдел аналитиков, писателей и редакторов, а где-то доку пишут разработчики (сделал — описал).

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

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

1. Фактор поддержки. Первая и самая очевидная из причин. Если документация хорошая, бо?льшая часть клиентов решит вопрос, не обращаясь в поддержку. Оставшимся саппорт кинет ссылку на инструкцию или быстро пройдётся по ней сам. Полную документацию можно использовать для создания чат ботов. Всё это сокращает время ответа клиентам, повышает их удовлетворённость, а также снижает затраты на поддержку.
2. Фактор выбора. Документация влияет на выбор клиента наравне с ценой, удобством, функциональностью. Это подтверждают наши исследования и обратная связь пользователей ISPmanager и DCImanager. В этом ключе дока перестаёт быть необходимостью поддержки, а становится конкурентным преимуществом, частью маркетинга.
3. Фактор лояльности. Если клиент ушёл, не разобравшись в доке на старте или в процессе, — это проблема. Привлечение клиента стоит слишком дорого, чтобы терять его из-за плохих статей.

Как сделать хорошую документацию

Определить цель. Это самая боль. Описать фичу просто ради описания или прокомментировать интерфейс — это не цель. Цель — это всегда полезное действие. Что должен знать и уметь пользователь, админ или разработчик после прочтения статьи? Например, создать сайт и привязать к нему домен, выпустить SSL-сертификат, настроить бэкапы и пр. То есть решить свою задачу.

Знать аудиторию. Мы делим клиентов на пользователей, администраторов и разработчиков. Но этого недостаточно для создания полезных текстов. Чтобы быстро понять аудиторию, можно сходить к UX и продакту, изучить запросы в поддержку и их ответы на нужную тему, послушать звонки в первую линию, посмотреть сайт и блог (маркетинг тоже пишет нужные вещи). И только после этого начинать писать.

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

Распространять статью после публикации. Если документация написана, скорее всего, это кому-нибудь нужно. Покажите её свету и используйте по максимуму: переведите, сошлитесь в продукте, отдайте маркетингу, поддержке. Не пишите в стол.

50 вопросов для работы над докой

Работая над документацией, мы повторяли одни и те же ошибки. Тратили на проверку статей слишком много времени, а гайд, который казался изначально панацеей, не помогал, потому что проблема была в подходе и содержании. Чтобы техписатели сами могли довести статью до ума, мы собрали в один список все вопросы, которые постоянно задавали (или забывали задать) им. Используйте, если тоже пишете доку.

Цели

1. Для кого я пишу статью? Кто будущий читатель: пользователь, администратор, разработчик?
2. Какие задачи стоят перед ним (jobs to be done)? Есть ли описание персоны?
3. Какой уровень подготовки этого пользователя? Что он уже знает? Что для него неочевидно?
4. Как можно объяснить это начинающему пользователю и при этом не злить продвинутого объяснением элементарных вещей?
5. Что ещё нужно объяснить пользователю, чтобы он понял основное содержание статьи?
6. В какой раздел документации подойдёт эта статья?
7. Эту статью или её часть надо продублировать в других разделах?
8. На какие статьи нужно ссылаться?
9. Может быть, эту статью следует сопроводить видеоинструкцией?

Источники информации

10. У текущих пользователей есть проблемы, связанные с темой статьи?
11. Как сейчас поддержка объясняет, что надо сделать?
12. Отдел маркетинга писал на эту тему статьи и новости в блог? Можно ли у них «подсмотреть» формулировки, структуру и др.?
13. Есть ли посвящённые этой теме разделы на сайте?
14. Что в сценарий закладывал UX и продакт-менеджер? Почему сделал это так?
15. Как этот вопрос описан у конкурентов?
16. В каких сферах ещё можно посмотреть лучшие практики?

Проверка содержания

17. Удалось ли достигнуть цели статьи?
18. Всё ли будет понятно более продвинутому пользователю?
19. Всё ли будет понятно начинающему пользователю?
20. Всё логично и последовательно? Нет «скачков» и пропастей?
21. Последовательность действий верна? Сможет ли пользователь достичь цели, следуя только этой инструкции?
22. Мы учли все кейсы/пути пользователя?
23. Статья вписывается в выбранный раздел?

Проверка вёрстки

24. Есть ли нечитабельные простыни текста? Можно ли заменить схемой?
25. Есть ли длинные абзацы?
26. Есть ли слишком короткие абзацы?
27. Есть ли слишком длинные списки?
28. Есть ли слишком вложенные сложные для восприятия списки (те, в которых больше двух-трёх уровней)?
29. Изображений достаточно?
30. Изображений не слишком много? Не иллюстрируем ли мы слишком очевидные шаги?
31. Если есть схемы, они понятны?
32. Таблицы не сложны для восприятия?
33. Страница в целом смотрится хорошо?

Литературное редактирование

34. Всё оформлено по гайду?
35. Соответствует ли стиль остальной документации?
36. Есть предложения, которые можно упростить?
37. Есть сложные термины, которые требуют пояснений?
38. Есть канцеляризмы?
39. Есть повторы?
40. Ничего не режет слух?

Финальная вычитка

41. Нет ли опечаток, ошибок в правописании и пунктуации?
42. С переносами, абзацами и разделами всё в порядке?
43. Все изображения подписаны?
44. Элементы интерфейса названы правильно?
45. Везде ли стоят ссылки? Они работают и ведут куда надо?

Сразу после публикации

46. В статье есть разделы, которые «подтягиваются» в другие статьи? Они оформлены макросами, чтобы изменения в одной статье автоматически применялись к другим?
47. На эту статью надо сослаться из других разделов? Если да, то из каких?
48. Надо добавить в продукт быструю ссылку на эту статью?
49. Надо ли отправить ссылку поддержке, маркетингу или другим отделам?
50. Надо ли отдать статью на перевод?

Этот список можно распечатать и положить на рабочий стол или повесить на стену. Или превратить в чек-лист. Часть вопросов можно вынести в бизнес-процесс. Наш, например, зафиксирован в общем процессе разработки в YouTrack. Задача по документации проходит по разным этапам и отделам, без написанной документации нельзя отдавать фичу в релиз.