В целом, пользовательская документация должна выполнять четыре основных функции и содержать четыре основных раздела, каждый из которых должен быть написан особым образом.
- вводные руководства;
- пошаговые инструкции;
- техническая справка;
- описания и объяснения.
| Руководства | Инструкции | Справка | Описания | |
|---|---|---|---|---|
| Ориентация | обучение | достижение цели | информация | понимание |
| Цель | позволить новичку начать | показать, как решить задачу | описать механизмы | объяснить решения |
| Форма | урок | серия шагов | сухое описание | аргументированное пояснение |
Руководство
Ориентировано на первое знакомство и изучение того, каким образом описываемая система может помочь решать конкретные задачи. Руководство должно быть рассчитано на полных новичков и не предполагать знакомства пользователей с любыми используемыми концепциями.
- Обучение через действие. Нужно позволить пользователю выполнять реальные действия в системе, причем эти действия должны быть подобраны таким образом, чтобы покрывать широкий спектр инструментов и операций, и выстроены по возрастанию сложности.
- Главное - начать. Первые шаги могут быть очень маленькими, а также не соответствовать “лучшим практикам”, потому что их цель - не создать идеального пользователя, а заинтересовать пользователя и показать ему ценность системы.
- Актуальность руководства. Руководство необходимо постоянно проверять и обновлять, чтобы оно было воспроизводимым на любых устройствах и для любого уровня подготовки пользователя.
- Быстрые видимые результаты. Любое действие ученика должно приводить к очевидному результату, каким маленьким бы он ни был. Связь результата и действия также должна быть очевидна.
- Конкретные действия, а не абстрактные концепции. В руководстве нет места теоретическим объяснениям и выводам.
- Минимально необходимые пояснения.
- Только необходимые шаги.
Инструкция
Ориентирована на решение реальной рабочей задачи, это своего рода рецепт для достижения конкретной желаемой цели. Предполагает более продвинутый уровень пользователя.
- Последовательность шагов. Можно начать не с самого начала и необязательно обеспечивать такую же повторяемость, как для руководств.
- Главное - достичь цели. Опять же, пояснениям и пространным размышлениям здесь не место.
- Решать конкретную задачу. В отличие от пользователя, читающего руководство, у читателя инструкции есть конкретная задача.
- Возможна гибкость в решении.
- Важно четкое название.
Справка
Техническое описание различных механизмов. Ориентировано на информацию, а не на обучение, содержит описание корректного использования каждого отдельного компонента системы.
- Отражать структуру системы. Навигация по компонентам системы и по справке должна быть максимально единообразной.
- Ничего, кроме технического описания. Но можно добавить примеры.
Объяснения
Проясняют какую-либо тему, ориентированы на понимание, возможно, выстроены в виде дискуссий (или произошли от обсуждений).
- Важен контекст.
- Важны рассмотренные альтернативы. В случае описания принятых решений важно показать, какие альтернативы были рассмотрены и по каким причинам отвергнуты.
- Естественный язык, никаких инструкций.