Главная » Хабрахабр » 50 вопросов для работы над документацией

50 вопросов для работы над документацией

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

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

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

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

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

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

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

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

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

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

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

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

Про редполитику

Редполитика оговаривает стиль изложения (формальный или неформальный), вёрстку и дизайн (скриншоты, их размеры, стили таблиц, списки), а также спорные вопросы (е или ё, написание терминов). Если у вас ещё нет такого документа, обязательно сделайте, он сокращает время и наводит порядок. Для вдохновения и понимания посмотрите доклад с конференции Яндекса и примеры руководств IBM или Mailchimp.

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

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. Часть вопросов можно вынести в бизнес-процесс. Задача по документации проходит по разным этапам и отделам, без написанной документации нельзя отдавать фичу в релиз.


Оставить комментарий

Ваш email нигде не будет показан
Обязательные для заполнения поля помечены *

*

x

Ещё Hi-Tech Интересное!

Векторные представления товаров, или еще одно применение модели Word2Vec

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

[Перевод] Внутренняя и внешняя линковка в C++

Всем добрый день! Надеемся, что она будет полезна и интересна для вас, как и нашим слушателям. Представляем вам перевод интересной статьи, который подготовили для вас рамках курса «Разработчик C++». Поехали. Хотите узнать, для чего используется ключевое слово extern, или как ...