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

Продолжение статьи, рассказывающей, возможно, очевидные вещи по созданию технической документации.

Первая часть - https://habr.com/ru/post/654411/

А теперь вернемся к причинам.

"Навигационные проблемы"

• Плохая структура документации или ее полное отсутствие

  Невероятно, но факт: мы до сих пор сталкиваемся с файлами справки, в которых информация идет сплошным текстом, не разбитым на разделы.

  Документация не должна становиться художественным произведением, где всё идет одним цельным файлом с «сюжетом». Пользователи ищут в документации решение конкретных проблем, а найти среди сплошного текста нужную информацию очень трудно, даже прибегая к «ctrl+f».

  Структурируйте вашу документацию. Поделите ее на разделы и опубликуйте в такой последовательности, в которой пользователь будет знакомиться с продуктом. Чтобы было проще, посмотрите руководства продуктов, разрабатываемых в крупных компаниях. По образцу работать станет быстрее и удобнее.

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

Некачественный контент

• Справка написана на неродном языке пользователя

  Работая над существующим продуктом или создавая новый, вы примерно понимаете, на каких географических рынках он будет использоваться. Если вашим продуктом пользуются не только в вашей стране, то стоит задуматься о локализации. И здесь я имею в виду не английскую версию документации, а локализированную версию справки на РОДНОМ языке пользователя.  Зачем?

  Английским в наше время владеет почти полтора миллиарда человек, но вот родным он является только для трехсот с лишним миллионов человек. При этом всего нас на планете больше семи миллиардов.

  Задумайтесь над этим, потому что часто даже такая образованная каста людей как врачи, не владеет английским.

• Неверная стилистика документации

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

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

• Документация содержит много ошибок

  Читать безграмотный текст, изобилующий ошибками, одно из самых неприятных занятий на Земле. Sic!

• Документация содержит мало графики и скриншотов

  Годы идут, но по-прежнему лучше один раз увидеть, чем сто раз услышать. Руководство становится приятнее и понятнее, если в нём есть скриншоты и иллюстрации, объясняющие функционал продукта. Без них пользователю требуется больше времени и усилий на то, чтобы понять, как работает программа или устройство. Облегчите ему задачу. Совместите текст и изображения.

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

• Отсутствие видео

  Пользователь ленив. Это стоит принять как данность и с этим ничего не сделать. Никто не хочет тратить время и читать руководство пользователя. Видео – отличный вариант показать последовательность действий для достижения какого-либо результата в программе.

  Создайте видео-каталог, в котором поэтапно будут показываться возможности вашей программы и способы их применения на практике. Разместите её на сайте продукта. Да, это сложно и займет много времени, но благодаря видео до пользователя будет с большей вероятностью доходить материал и с меньшей вероятностью он будет обращаться в техподдержку.

На этом мне бы хотелось закончить эту серию статей и пожелать вам удачи в ваших разработках!

Но перед этим упомяну софт, над которым, как уже говорил в первой части, я работаю много лет – Dr.Explain.

Возможно в нем вам станет проще и быстрее разрабатывать пользовательскую документацию.

Спасибо!