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

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

В состав технической документации как правило входят две основные части:

Руководство пользователя (User's Guide), описание наиболее типичных пользовательских задач, ориентированное в основном на начинающих пользователей.

Справочник пользователя (User's Reference), полное описание функциональности продукта.

Эти части могут существовать и в интегрированном виде.

Существует несколько сценариев использования документации пользователем:

"Быстрый старт", т.е. поиск сведений об установке, настройке, запуске и начале работы с программным продуктом.

Ознакомительное чтение для освоения продукта в целом, решения наиболее типичных задач.

Целевой поиск путей решения той или иной задачи.

Целевой запрос справочной информации по избранной функции или элементу интерфейса программы.

Методическое освоение программного продукта, детальное знакомство со всеми нюансами его работы.

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

Общая логика изложения в документации сводится к следующему:

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

Перечисляются типичные внешние задачи, которые могут решаться с использованием программного продукта.

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

Даются исчерпывающие инструкции по выполнению конкретных процедур в программе.

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

Недопустимо ставить цель и не указывать способ её достижения. Недопустимо описывать способ достижения цели, не сформулировав самой цели. Недопустимо смешивать внешние и внутренние объекты (например, документ как таковой и файл документа).

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

Размещение информации может выглядеть примерно так:

Вводные главы - "быстрый старт".

Руководство пользователя - ознакомительное чтение.

Справочник пользователя - целевой поиск и целевые запросы, методическое освоение продукта.

Специальные главы - дополнительная информация о сервисных функциях типа экспорта и импорта, поиска и т.п. Также относится к целевому поиску и целевым запросам, методическому освоению продукта.

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