Как сделать хорошее руководство пользователя

[SUNSHINE]

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

Теория

Пользователи читают документацию в надежде получить от этого процесса знания.
Существуют три типа знаний — Как (Что), Зачем и Почему:
Как (Что). "Как мне сохранить документ?". Что делает эта кнопка?".
Почему. "Почему все данные исчезли? Я ведь ничего не стирал"
Зачем. "Зачем эту кнопку хорошо нажимать при записи?"

Содержание

Пишите компактно.
Избегайте прилагательных.
Командуйте. Фраза "для запуска программы нужно щелкнуть на соответствующую иконку" всегда хуже фразы "щелкните на соответствующую иконку, чтобы запустить программу".
Старайтесь делать абзацы покороче.
Большинство текста может быть совершенно чётко разделено по степени важности для пользователя, т.е. часть информации описывает действие, а другая его объясняет.
Старайтесь не смешивать текст разной важности в одном абзаце.
Старайтесь поддерживаться фиксированной структуры глав.
У каждой главы должно быть введение, кратко описывающее её содержание.

Форма

Пиктограммы, расположенные в основном тексте, сильно снижают читабельность. Постарайтесь расположить их на полях (к сожалению, чаще всего невозможно).
Всё, что трудно передать словами, передавайте с помощью иллюстраций.
Не помещайте в иллюстрации несущественные детали. Лучше будет менее красиво, но зато более понятно.
Не экономьте бумагу.
Две разные темы не должны описываться на одной странице.
Заголовки не должны теряться на фоне текста, лучшее место для них — поля.
В руководстве пользователя, в отличие от остальных типов литературы, номера страниц имеют значительно большее значение. Делайте их возможно более разборчивыми.

И вдобавок:

Руководство пользователя без предметного указателя никуда не годится. (Нормальный человек сначала лезет в предметный указатель, и только затем — в оглавление).
Предметный указатель лучше всего писать параллельно с писанием основного текста.
Перекрестные ссылки должны быть. Причем ни в коем случае нельзя ссылаться только на название раздела — обязательно должен быть и номер страницы (на название раздела надо ссылаться только в том случае, если на одной странице может быть больше одного раздела).
Разносите информацию. Если размер получающейся книги велик (более сотни страниц), разделите её на несколько отдельных книжечек (наиболее часто используют деление на три книги — введение, собственно руководство пользователя и разрешение проблем).
Руководство пользователя нужно обновлять параллельно с обновлением продукта. Пользователи ненавидят устаревшие документации.