Часть первая
Данная статья не предполагает каких-то заумных и крайне неочевидных советов по написанию и проверке технической документации. Многие из перечисленных «советов» многим покажутся очевидными, но из раза в раз, анализируя документацию наших пользователей, мы сталкиваемся с одними и теми же банальными ошибками, которые чаще всего происходят из-за фактора «забыл». Так что данный пост можно расценить как памятку не техническому писателю.
Приятного чтения.
За долгое время работы над программой для написания этих самых «хелпов», наша команда рассмотрела и проанализировала множество сторонних проектов, руководители которых обращались к нам за помощью. Чаще всего с их стороны были вопросы о реализации тех или иных приемов в пользовательской документации к их продуктам. И на основе такого опыта мы сделали два вывода:
1) Документация востребована и ее читают.
2) Если ей не пользуются, то это происходит по следующим причинам:
"А где найти руководство"
На сайте программы отсутствует ссылка на файл справки
Всем уже давно известно, что хорошо бы выложить руководство пользователя на сайт, но иногда кто-то потом просто забывает создать отдельную кнопку в меню со ссылкой на документацию. Решение этой проблемы очевидно: добавьте документацию в меню сайта, чтобы никто не мучился и не искал ваш «хэлп».
Документацию сложно найти
Да, ошибка похожа на предыдущую, но отличается тем, что разработчик не забыл указать ссылку на документацию, а решил, что пользователь сам спокойно сможет ее отыскать где-то на задворках сайта. Это не так. Пользователь ленив, помните это. Просто добавьте на видное место ссылку на документацию.
Отсутствует «справка» в меню
Решение простое: пробегитесь глазами по интерфейсу программы и попробуйте найти место для элементов управления, которые будут открывать файл-помощник.
"F1 не работает!"
Традиционно, контекстная справка в программах активируется нажатием клавиши F1. Поэтому пользователи в первую очередь будут нажимать эту клавишу и если она не будет работать, то скорее всего человек решит, что справки в вашей программе просто нет.
"Что-то не то с форматом"
Формат документа не поддерживается
Данная ошибка часто встречалась у клиентов, которые разрабатывали межплатформенные программы. Создавая файл справки, разработчики часто забывали, что его могут открывать не только пользователи «винды» и интегрировали справку с продуктом только в формате CHM. Этот формат отлично поддерживается Windows и изначально умеет просматривать CHM файлы. Но для других операционок CHM не является "родным", и ваш клиент замучается открывать его например на MacOS или Ubuntu.
Формат документа не удобен для чтения на конкретном устройстве или в конкретной среде
Казалось бы, универсальным решением универсальности документации являются HTML и CHM форматы. Имея доступ в интернет, пользовательскую документацию опубликованную на сайте можно открыть на любой платформе, а контекстно-зависимую справку просто нажав на кнопку F1.
Однако стоит помнить, что интернет, по разным причинам, в наше время доступен не всем и не всегда, и пользователь может прибегнуть к документации, не находясь в программе.
Решение простое – поставляйте ваш продукт вместе с документацией в формате PDF или разместите PDF файл на сайте, чтобы «мануал» можно было скачать на устройство. В таком случае у пользователя всегда будет под рукой локальная версия справки, к которой он сможет обратиться за помощью.
"Навигационные проблемы"
Отсутствует поиск по документации
Техническая документация к продукту сама по себе подразумевает большое количество разделов и даже с хорошей и логичной структурой пользователю будет тяжело найти в ней нужную информацию. Здесь поможет «поиск» по документу. Но ведь что в PDF, что в CHM формате функция поиска реализована по умолчанию. Тогда почему здесь эта ошибка?
Потому что разработчики часто забывают, про онлайн документацию, которая является набором разных HTML файлов. В ней браузер может найти конкретные фразы только на странице, открытой в данный момент. Для поиска по всем разделам документации не забудьте создать особый скрипт или используйте Google Site Search.
На этом я бы хотел закончить первую часть данной статьи.
Надеюсь, что она была полезна и интересна.
Вторая часть - https://habr.com/ru/post/659191/
P.S. Под технической документацией в данной статье я имею в виду только руководство пользователя.