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

0
Акашева Василиса Игоревна10/23/2020

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

И. Варнина. 50 вопросов для работы над документацией. [Электронный ресурс] HABR. — Режим доступа: habr.com/ru/company/ispsystem/blog/431456. — Дата обращения: 23.10.20.
Следующая статья
Бизнес и экономика
Как напугать социальной рекламой с помощью Л. С. Выготского
А вы знали, что можно найти несколько работающих идей для социальной рекламы всего за несколько минут? Причём не раз в год, когда накопятся впечатления, а прямо здесь и сейчас. Давайте разберёмся, как это возможно. Часто, чтобы привлечь внимание к социальной проблеме, в рекламу закладывают элементы, вызывающие страх. Люди не могут относиться несерьёзно к тому, что их пугает, поэтому такой контент сразу привлекает внимание. Многие авторы находят идеи интуитивно или случайно, но есть и те, кто использует специальные техники. В этой статье мы разберём авторс...
Бизнес и экономика
Как напугать социальной рекламой с помощью Л. С. Выготского
Бизнес и экономика
СамоНеОрганизация. Почему посиделки у кулера не помогут работать лучше
Бизнес и экономика
Почему люди не будут пользоваться знаниями, инструментами и практиками
Бизнес и экономика
10 типовых ошибок коммуникаций на промышленном предприятии
Бизнес и экономика
«Кровь, тяжёлый труд, слёзы и пот» — как создавать сильные речи по Черчиллю
Бизнес и экономика
Почему одни профессии оплачиваются выше других: взгляд Адама Смита
Бизнес и экономика
«Трудности» перевода в IT-проектах и как их преодолеть
Бизнес и экономика
Уставы Пахомия: переход от индивидуальной практики к зачаткам корпоративной культуры в IV веке
Бизнес и экономика
Иллюзия работы, или почему не работает самодиагностика процессов на предприятии
Бизнес и экономика
Junior UX/UI собеседование: как произвести впечатление на будущих коллег?
Бизнес и экономика
Как соревнование и конкуренция ведут общество вперёд
Бизнес и экономика
Один в поле не воин, или как собирать рацпредложения на предприятии
Бизнес и экономика
Чем полезно разделение труда: выдержки из Адама Смита
Бизнес и экономика
Как фиксировать и внедрять лучшие практики в компании – инженер Гаррингтон Эмерсон
Бизнес и экономика
Концептуальная целостность по Фредерику Бруксу – на примере интерфейса WIMP
Бизнес и экономика
Как спровоцировать клиента на импульсивные покупки