"Данная статья не предполагает каких-то заумных и крайне неочевидных советов по написанию и проверке технической документации. Многие из перечисленных «советов» многим покажутся очевидными, но из раза в раз, анализируя документацию наших пользователей, мы сталкиваемся с одними и теми же банальными ошибками, которые чаще всего происходят из-за фактора «забыл». Так что данный пост можно расценить как памятку не техническому писателю..."
Продолжение статьи, рассказывающей, возможно, очевидные вещи по созданию технической документации.
Первая часть - https://habr.com/ru/post/654411/
А теперь вернемся к причинам.
"Навигационные проблемы"
Плохая структура документации или ее полное отсутствие
Невероятно, но факт: мы до сих пор сталкиваемся с файлами справки, в которых информация идет сплошным текстом, не разбитым на разделы.
Документация не должна становиться художественным произведением, где всё идет одним цельным файлом с «сюжетом». Пользователи ищут в документации решение конкретных проблем, а найти среди сплошного текста нужную информацию очень трудно, даже прибегая к «ctrl+f».
Структурируйте вашу документацию. Поделите ее на разделы и опубликуйте в такой последовательности, в которой пользователь будет знакомиться с продуктом. Чтобы было проще, посмотрите руководства продуктов, разрабатываемых в крупных компаниях. По образцу работать станет быстрее и удобнее.
Кроме того, вам самим будет легче заниматься проектом с логичной и продуманной структурой, особенно, когда документация будет требовать обновления и дополнения.
Некачественный контент
Справка написана на неродном языке пользователя
Работая над существующим продуктом или создавая новый, вы примерно понимаете, на каких географических рынках он будет использоваться. Если вашим продуктом пользуются не только в вашей стране, то стоит задуматься о локализации. И здесь я имею в виду не английскую версию документации, а локализированную версию справки на РОДНОМ языке пользователя. Зачем?
Английским в наше время владеет почти полтора миллиарда человек, но вот родным он является только для трехсот с лишним миллионов человек. При этом всего нас на планете больше семи миллиардов.
Задумайтесь над этим, потому что часто даже такая образованная каста людей как врачи, не владеет английским.
Неверная стилистика документации
Хорошо это или плохо, но мы все подвержены профессиональной деформации. Даже в этой статье можно наблюдать подобную ситуацию. Из-за сферы нашей деятельности, слова «релиз», «мануал», «хэлп», «техлид» и тому подобные глубоко встроились в нашу речь, и мы иногда не осознаем, что многим людям наши «профессионализмы» не понятны.
Постарайтесь подобрать более доступный неподготовленному читателю аналог из общеупотребительных слов. Руководство пользователя в первую очередь должно быть информативно и полезно для самого пользователя.
Документация содержит много ошибок
Читать безграмотный текст, изобилующий ошибками, одно из самых неприятных занятий на Земле. Sic!
Документация содержит мало графики и скриншотов
Годы идут, но по-прежнему лучше один раз увидеть, чем сто раз услышать. Руководство становится приятнее и понятнее, если в нём есть скриншоты и иллюстрации, объясняющие функционал продукта. Без них пользователю требуется больше времени и усилий на то, чтобы понять, как работает программа или устройство. Облегчите ему задачу. Совместите текст и изображения.
Добавляйте к изображениям пояснительные выноски, чтобы пользователь мог наглядно увидеть, где что находится, и как оно работает.
Отсутствие видео
Пользователь ленив. Это стоит принять как данность и с этим ничего не сделать. Никто не хочет тратить время и читать руководство пользователя. Видео – отличный вариант показать последовательность действий для достижения какого-либо результата в программе.
Создайте видео-каталог, в котором поэтапно будут показываться возможности вашей программы и способы их применения на практике. Разместите её на сайте продукта. Да, это сложно и займет много времени, но благодаря видео до пользователя будет с большей вероятностью доходить материал и с меньшей вероятностью он будет обращаться в техподдержку.
На этом мне бы хотелось закончить эту серию статей и пожелать вам удачи в ваших разработках!
Но перед этим упомяну софт, над которым, как уже говорил в первой части, я работаю много лет – Dr.Explain[ссылка удалена модератором].
Возможно в нем вам станет проще и быстрее разрабатывать пользовательскую документацию.
Спасибо!
