Справочная система

• Общие сведения
• Содержание документа
• Методика и стиль изложения
• Примеры

Общие сведения

Документация:	программная/эксплуатационная/документация пользователя
Предмет:	программа, комплекс, программный компонент комплекса или системы
Аудитория:	пользователь, оператор, администратор, системный администратор, программист и др.
Задачи:	как можно быстрее предоставить пользователю, оператору, администратору, системному администратору необходимые сведения о программе непосредственно во время работы с ней
Стандарты:	ISO/IEC 26514:207

Содержание документа

Полноценная справочная система состоит, по крайней мере, из двух частей: общей и контекстной.

В общую часть обычно включают материал всех имеющихся руководств: пользователя или оператора, администратора, системного администратора и других документов, разумеется при наличии таковых. Более того, материал, который из-за большого объема невыгодно печатать на бумаге или неудобно искать в линейном документе, нередко включают только в справочную систему. В особенности это касается описаний библиотек функций и классов.

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

Многие авторы не включают в справочную систему разделы, ознакомление с которыми, по логике вещей, предшествует работе с программой: системные требования, установка программы и т. п. Но это спорное решение, поскольку оно может обмануть ожидания читателя.

В контекстную часть справочной системы включают:

• описание каждого режима и диалогового окна;
• подсказки по элементам главного окна, окон документов и диалоговых окон;
• подсказки по пунктам меню и кнопкам панелей инструментов;
• подсказки по употребляемым терминам.

Общей частью читатель пользуется как электронной книгой.

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

Многие форматы давно позволяют включать в справочные системы мультимедийный контент: звуковые и видео-файлы, а также Flash. Однако авторов, желающих воспользоваться этими возможностями, находится совсем не много. Сложно сказать, чем это объясняется, может быть, трудоемкостью создания таких материалов, а может, неготовностью пользователей воспринимать техническую информацию в такой форме. В пользу последнего предположения говорит тот факт, что оснащать свои справочные системы учебными фильмами не торопятся даже корпорации, которые явно не испытывают дефицита средств и квалифицированных специалистов.

Методика и стиль изложения

Справочная система — это гипертекст. О том, каким требованиям он должен удовлетворять, чтобы его преимущества перед текстом линейным не были сведены на нет, написано много книг и еще больше статей. Речь в них идет преимущественно о веб-сайтах, от которых техническая документация, конечно, отличается. Не имея возможности глубоко вникать эту проблематику здесь и сейчас, приведем несколько основных правил написания гипертекста.

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

1. Следует стремиться к тому, чтобы каждый раздел представлял собой самодостаточную статью, при ограниченном объеме в целом (пускай не стопроцентно) понятную читателю в отрыве от остального материала. Иначе говоря, раздел должен быть чем-то вроде статьи в энциклопедии или обстоятельного ответа на заданный кем-то вопрос. Это может достигаться, в частности, более активным дублированием текста (определений, концепций), чем в линейном документе.
2. Если полное понимание раздела невозможно без ознакомления с некоторыми другими разделами справки, на них должны быть сделаны ссылки. Также настоятельно рекомендуется делать ссылки на определения терминов, употребляемых в тексте раздела.
3. В гипертексте исключены (поскольку лишены смысла) неявные ссылки из одного раздела в другой, которые в линейном тексте делаются с помощью выражений «как было сказано выше», «как будет показано ниже» и т. п.

Тем не менее, на практике справочная система часто представляет собой текст руководства пользователя, представленный в определенном электронном формате. Что не идет на пользу делу, но значительно проще и дешевле.

Примеры

Программный комплекс ИНЭК-Страховщик 5.0, модуль «Бухгалтерия». Справочная система в формате Microsoft HTML Help

ИНЭК-Страховщик — программный комплекс, предназначенный для автоматизации деятельности страховых компаний. Версия 5.0 программного комплекса включала в себя несколько прикладных модулей, одним из которых был модуль «Бухгалтерия». Программный комплекс ИНЭК-Страховщик выпускается компанией ИНЭК. Техническая документация на его пятую версию была разработана «Философтом». На рис. 1 показано окно справочной системы модуля «Бухгалтерия».

Базовая автоматизированная система компании Rover Computers. Электронное руководство пользователя на базе веб-публикации

Компания Rover Computers производит и продает в России всевозможную компьютерную технику, коммуникаторы, средства мобильной связи. Управление обширной коммерческой деятельностью компании обеспечивается оригинальной автоматизированной системой, разработанной на базе Lotus Notes (по крайней мере, так обстояли дела в 2003 г.). По заказу Rover Computers «Философтом» было создано электронное руководство пользователя для сотрудников компании, работающих в этой системе. Руководство реализовано в виде веб-публикации (рис. 2).