Что из себя представляют справочные файлы
Файлы справочной информации содержат информацию о содержании справочной системы. Информация включает в себя:
7.1 Файл оглавления
Файл оглавления (Table of Contents, TOC) - это XML файл, который описывает содержание и формат оглавления. Это обычно представляется как закладка как Contents .
7.1.1 Элементы TOC
Table 7-1 описывает элементы, используемые в файле оглавления:
Table 7-1 TOC File Elements
Определяет оглавление. Этот элемент содержит элементы <tocitem> . Элемент <toc> поддерживает следующие атрибуты:
version - Версия спецификации формата файла оглавления. Здесь задокументирована Версия 1.0 .
Определяет элемент оглавления. Элемент <tocitem> может содержать другие элементы <tocitem> для создания иерархической структуры разделов. "tocitem_1", вставленный внутрь "tocitem_2", означает нахождение иерархически "tocitem_1" внутри "tocitem_2." Элемент <tocitem> поддерживает следующие атрибуты:
target - Идентификатор темы (ID) отображается, когда этот элемент выбран пользователем. Идентификаторы тем сохраняются в map-файл. Родительский узел (то есть элемент, который содержит другие, которые находятся ниже в иерархии) может включать или не включать цель. Если он не имеет цели, то после выбора этотого узла будет просто отображены его дочерние элементы и узлы.
text - Текст, который отображается в оглавлении для данного элемента.
image - Изображение для отображения рядом с этим пунктом. Значением этого атрибута является ID изображения, указанный в Map-файле.
В следующем примере показан краткий файл оглавления:
Это описание даст следующую ТОС иерархию:
- Introduction to My Product
- About My Product
- My Product Architecture
- About Feature One
- About Feature Two
- About Feature Three
- Learning My Product
Guide to Documentation
7.2 Индексный файл
Индексный файл представляет собой XML-файл, описывающий содержание и структура индекса. Это обычно отображается как закладка Index .
7.2.1 Элементы Index
Table 7-2 describes the elements used in the index file:
Table 7-2 Элементы индексного файла
Определяет индекс. Он может содержать теги <indexitem> и <indexentry> .
Определяет элемент индекса, который появляется в списке ключевых слов. "index_item_1", вставленный внутрь "index_item_2", означает нахождение иерархически "index_item_1" в "index_item_2", указан с отступом ниже "index_item_2" в индексе. Oracle Help в настоящее время поддерживает только два уровня ключевых слов. Index отображение (вьюшка) уничтожает любую вложенность кроме двух уровней.
Если элемент индекса имеет более одной темы связанной с ним, то такие темы должны быть перечислены как опреелённые элементы <indexentry> index-записей.
Элемент <indexitem> имеет следующие атрибуты:
target - Идентификатор темы (ID), определенный в map-файле, отображается при выборе записи пользователем.
Определяет индекс-запись, отображаемую в списке тем, когда родительский элемент индекса выбран в index-списке. Этот тег использует следующиt атрибутs:
target - Идентификатор темы (ID), определенный в map-файле, отображается при выборе записи пользователем.
Этот пример показывает очень короткий Index-файл:
Файл, в приведённом выше примере, генерирует такой Index-список:
Если пользователь выбирает Adding a new sheet to a workbook из этого списка, то будет отображаться список следующих тем:
Список тем появляется в нижней части индекс-панели, в отличие от темы отступом, Adding an icon to a sheet и Adding an icon to a workbook , которые показаны вверху списка ключевых слов в верхней части индекс-панели.
Выбрав ключевое слово, которое не имеет указателя, но имеет напрямую связанные цели (например, Adding an item to a sheet ), отображаем в список тем тот же текст, что и в список ключевых слов. Поскольку Oracle Help отображает индекс, лучше никогда не использовать цель в теге <indexitem> . Вместо этого всегда используйте теги <indexentry> , чтобы указать темы, связанные с <indexitem> -- даже когда есть только одна цель для ключевого слова.
Другими словами, следующий код:
. лучше, чем этот код:
7.3 Поисковый индексный файл
Поисковый индексный файл используется тогда, когда пользователь выполняет поиск текста в Oracle Help, обычно на закладке "Поиск". Этот файл использует собственный бинарный формат. Любая сторонний инструмент разработки Help-a, который поддерживает Oracle Help, должны быть в состоянии генерировать этот файл. Кроме того, OHJDK включает в себя две утилиты, которые генерируют индексный файл поиска:
Мастер разработки Helpset предоставляет ограниченную поддержку разработки, включая создание поисковых индексов. Для получения дополнительной информации смотрите Chapter 10, "Authoring Oracle Help Systems".
Поисковый Индексатор Текста - это Java утилита командной строки, которая генерирует поисковые индексы. Для получения дополнительной информации смотрите Chapter 12, "Using the Text Search Indexer".
7.4 Файл ссылок
Файл ссылок представляет собой XML-файл, определяющий ID ссылок и связывает их с несколькими идентификаторами (ID) тем (которые определяются в Map-файле). ID ссылки или ключевое слово ссылки может использоваться с протоколом alink в файле темы для отображения списка ссылок на темы, который связанны с ID. Иными словами, ассоциативные ссылки позволяют связать HTML-ссылку с несколькими целями. Пользователь может затем выбрать, какой цели следовать.
7.4.1 Элементы файла ссылок
Table 7-3 описывает элементы, используемые в файле ссылок:
Table 7-3 Элементы файла ссылок
Определяет файл ссылок. Элемент <link> может содержать только элементы <linkitem> и их дочерних элементов <linkentry> .
Определяет ассоциативную ссылку. Элемент <linkitem> может содержать только элементы <linkentry> . Он имеет следующие обязательные атрибуты:
topicid - Определяетм ID ссылки.
Определяет запись в списке ссылок, отображаемую при нажатии на ассоциативную ссылку. Этот элемент поддерживает следующие атрибуты:
target - Задает идентификатор темы (ID), определенный в map-файле, для отображения при выборе записи пользователем.
text - Текст, отображаемый в списке ссылок
В следующем примере определены две ассоциативных ссылки:
Используя первую ID-ссылку из этого примера, вы могли бы определить ссылку <a href="alink:dog_links">dogs</a> . Когда пользователь выберет ссылку dogs , то будет отображаться следующий список ссылок:
About Dogs
A List of Dog Species
Dog Stories
Dog LoreВыбор About Dogs отобразит тему, сопоставленную ID about_dogs в Map-файле.
Желательно, чтобы каждая программа имела справочную систему, при помощи которой пользователь мог получить исчерпывающую информацию о программе, о том, как с ней работать. Справочная система представляет собой набор файлов определенной структуры, использую которые программа Winhelp, являющаяся составной частью Windows, выводит справочную информацию, которая находится в hlp-файле.
- Подготовка справочной информации (создание файла документа справочной информации).
- Преобразование файла справочной информации в файл справочной системы.
После того как создан файл справочной информации системы (rtf-файл), можно приступить к созданию справочной системы (hlp-файла). Для этого удобно воспользоваться программой Microsoft Help Workshop, которая находится в файле Hcw.exe; который поставляется отдельно или вместе с Delphi (или в C++ Builder) Запускается Microsoft Help Workshop через файл Hcw.exe.
После запуска программы Microsoft Help Workshop на экране появляется главное окно программы. Основным файлом компилятора является файл проекта, который объединяет такие элементы, как текстовые файлы справок, опции, номера контекстов, и позволяет создать из них справочный файл. Для того чтобы приступить к созданию справочной системы, нужно из меню File выбрать команду New, затем в открывшемся диалоговом окне Project File Name указать тип создаваемого файла - Help Project. Далее следует выбрать папку, где находится программа, для которой создается справочная система, и где уже должен находится файл документа справочной системы (rtf-файл). Затем в поле Имя файла нужно ввести имя файла проекта справочной системы. Файлу проекта присваивается расширение HPJ.
Используя окно проекта справочной системы, можно добавить необходимые компоненты в проект, задать характеристики окна справочной системы, выполнить компиляцию проекта и пробный запуск созданной справочной системы. Для того чтобы добавить в проект файл справочной информации, нужно нажать на кнопку Files и в открывшемся диалоговом окне Topic Files - кнопку Add. В итоге открывается стандартное окно Открытие файла, позволяющее выбрать нужный rtf-файл.
В результате нажатия на кнопку ОК появляется окно Window Properties, в поле Title bar text вкладки General которого нужно ввести заголовок главного окна создаваемой справочной системы.
Используя вкладку Position диалогового окна Window Properties, можно задать положение и размер окна справочной системы.
На вкладке Position находится кнопка Auto-Sizer, при нажатии которой открывается окно Help Window Auto-Sizer, размер и положение которого определяется содержимом полей вкладки Position. При помощи мыши можно менять размер и положение этого окна. После нажатия кнопки ОК координаты и размер окна Help Window Auto-Sizer будут записаны в поля вкладки Position.
Используя вкладку Color, можно задать цвет фона области заголовка раздела справки и области текста справки. Для этого надо нажать соответствующую кнопку Change и в стандартном окне Цвет выбрать нужный цвет.
В этом окне нужно нажать кнопку Add и в поле Topic ID, открывшегося диалогового окна Add Map Entry, ввести идентификатор раздела справки, а в поле Mapped numeric value - соответствующее идентификатору числовое значение. В поле Comment модно ввести комментарий - название раздела справочной системы, которому соответствует идентификатор. Далее приведено окно проекта справочной системы после добавления rtf-файла, установки характеристик главного окна справочной системы и назначения числовых значений идентификаторов разделов.
После того как будет подготовлен файл проекта, можно выполнит компиляцию, щелкнув на находящейся в окне проекта кнопке Save and Compile. Однако первый раз компиляцию проекта справочной системы лучше выполнить выбором из меню File команды Compile, в результате выполнения которой открывается диалоговое окно Compile a Help File.
Для создания полноценной справочной системы необходимо создать cnt-файл, в котором будут храниться названия тем и разделов справочной системы. В программе Help Workshop нужно создать новый проект File->New, в открывшемся диалоговом окне выберите тип создаваемого файла - Help Contents. Откроется окно проекта, в котором нужно заполнить поле Default filename - имя файла справки (RS.hlp) и Default title - заголовок окна справочной системы.
Для добавления темы нужно нажать кнопку Add Below - откроется диалоговое окно добавления тем и разделов. Под темой понимается то, что в справочной системе отображается как иконка закрытой книжки, щелчок на которой приведет к раскрытию выпадающего списка разделов справочной системы, а раздел в справочной системе отображается как иконка листа со знаком вопроса, щелчок на которой приведет к открытию соответствующего раздела. Добавить тему можно и с помощью кнопки Add Above - эти кнопки различаются тем, что при добавлении Add Above - раздел располагается выше выделенного раздела, а Add Below - ниже. Для добавления темы необходимо установить переключатель на Heading и заполнить поле Title - название темы.
При добавлении раздела, переключатель следует установить на Topic и заполнить поля Title - название раздела (Журнал оплаты); Topic ID - идентификатор раздела (IDH_5); Help file - имя файла помощи (RS.hlp); Window type - тип окна, в котором будет отображаться раздел (main).
После создания cnt-файла его нужно добавить в проект справки. Для этого надо открыть ранее созданный проект справочной системы, нажать кнопку Options и в открывшемся окне на вкладке Files в поле Contents file ввестиите имя cnt-файла.
Для того чтобы на вкладке Указатель справочной системы отображались ключевые слова, выбрав которые можно было бы перейти на соответствующий раздел справки нужно использовать сноску K.
Используя сноску $ можно задать названия разделов, которые будут отображаться на вкладке Поиск.
После того как были внесены изменения в проект, необходимо файл справочной системы перекомпилировать.
Для того, что бы во время работы программы пользователь, нажав клавишу F1, мог получить справочную информацию, надо чтобы свойство Файл справки формы содержало имя файла справочной системы, а свойство Идентификатор справки - числовой идентификатор раздела справочной информации, который должен быть выведен.
Файл справочной системы приложения лучше поместить в ту папку, в которой находится файл исполняемой программы. Это позволит использовать одно и то же значение свойства Файл справки во всех экземплярах приложения и не помешает установке приложения в любую папку пользователя. Если в значении этого свойства не указан путь, Microsoft Access будет искать файл справочной системы в каталоге приложения. Если в момент нажатия клавиши F1 фокус находится на элементе управления, для которого не был создан пользовательский раздел справочной системы, то будет выведен раздел пользовательской справки для формы. Если раздел пользовательской справки для формы также отсутствует, открывается окно помощника по Office. Раздел пользовательской справки не может быть выведен на экран с помощью помощника.
Для создания файла справки можно использовать также Microsoft HTML Help Workshop- для создания файлов справочной системы в гипертекстовом формате.Справочная система программы, или попросту файл справки, предназначен для предоставлению пользователю программы полной и исчерпывающей информации, о том как работать с программой и для чего данный программный продукт нужен. Справочная система должна удовлетворять следующим требованиям:
Установив на компьютер новую программу, мы чаще всего начинаем осваивать ее методом тыка. Если пользовательский интерфейс программы интуитивно понятен, это быстро приносит результат. Если разобраться с наскока не получилось, а программа очень нужна, мы ищем в Интернет видеоуроки, инструкции, описания в блогах. Иногда смотрим, есть ли документация на сайте разработчика или нажимаем на клавиатуре F1, чтобы открыть справку или помощь. Что же такое справка и почему ее также называют помощью? Для чего она нужна? Какая она бывает, и какая она должна быть? Давайте разберёмся.
Для чего нужна справка
Справка нужна для того, чтобы помочь нам разобраться, как использовать программу, как с ее помощью решить какую-либо задачу или проблему. То есть, справка — это, прежде всего, документация для пользователя. Символом справки чаще всего является знак вопроса или спасательный круг. Отсюда и варианты термина справка и помощь (от англ. help).
Что такое справка
Приведем несколько определений. «Документацией пользователя программного продукта называется полный комплект документов, поставляемых в печатном или другом виде, который обеспечивает целевое применение продукта пользователем, а также является неотъемлемой частью этого продукта» (Кагарлицкий 2012: 32).
Для справки можно предложить следующее определение: справка или помощь – это пользовательская документация в электронном формате, встроенная в программный продукт. Последнее утверждение не следует понимать всегда буквально. «Встроенная» значит: является неотъемлемой частью программного продукта, вызывается из данного программного продукта.
Справка или помощь поставляется в электронном виде. Она может состоять из одного или нескольких файлов, содержащих оглавление, текст, рисунки, или определяющих внешний вид и функционал справки (файлы скриптов, таблицы стилей, шрифты и т.д.). Поэтому в отношении справки часто используются термины справочная система (от англ. online help) и файлы справки (от англ. help files).
Где могут храниться файлы справки
По месту расположения файлов справка может быть локальной, удаленной, либо комбинированной:
- Локальная справка в прямом смысле встроена в программный продукт. Она, как правило, входит в дистрибутив и устанавливается в одну папку с программой. Иногда справку можно дополнительно загрузить из Интернет во время установки.
- Удаленная справка обычно расположена на сайте компании-разработчика. Чаще всего это справка в формате WebHelp. При вызове из программного продукта такая справка открывается в браузере, используемом по умолчанию.
- Комбинированная справка сочетает локальные и сетевые ресурсы. Часть справки хранится на локальном компьютере, а часть – подгружается из сети Интернет при обращении к соответствующим разделам (например, справка в Windows XP).
Платформы и форматы справки
Считается, что справка должна быть в любом приличном приложении. Для программ, работающих под управлением ОС Windows, стандартом справки является формат CHM (HTML Help). В Linux, iOS и Android — это может быть WebHelp или PDF. Если в приложении нет справки, есть смысл задуматься о его надежности. Ведь компания-разработчик могла сэкономить не только на справке!
Минимальный функционал справки
Принято считать, что справка или помощь должна минимально обладать следующими функциями:
- Содержание / Оглавление. В справке должно быть оглавление, позволяющее перейти в любой раздел справки. Оглавление должно быть доступно в любом разделе. В классическом варианте это динамическое оглавление, обладающее древовидной структурой, разделы которого можно разворачивать и сворачивать.
- Указатель — это упорядоченный по алфавиту список ключевых слов, позволяющий перейти напрямую в тот или иной раздел справки.
- Поиск — полнотекстовый поиск, позволяющий найти в справке нужную информацию по одному или нескольким ключевым словам.
- Перекрестные ссылки. Перекрестные ссылки связывают части структурированной информации между собой и позволяют перемещаться между связанными по смыслу разделами.
В справке может быть и дополнительный функционал: возможность добавлять закладки на разделы (Избранное, Закладки), печать и другие функции, менее востребованные в электронном формате.
Какой должна быть хорошая справка
Универсального ответа на данный вопрос не существует. Та справка, которая будет соответствовать заданным критериям качества, и будет считаться качественной. Критерии качества, в свою очередь, зависят от стороны, которая их будет определять. Это может быть не только разработчик справки или пользователь, но и заказчик, инвестор или другой участник процесса разработки.
Мне ближе критерии качества, сформулированные сторонниками топик-ориентированного подхода (от англ. topic-based writing; IBM Style Guide 2011: 115) или тематического принципа (Кагарлицкий 2012: 89). Приведу основные требования к качеству справки (Developing Quality Technical Information 2004: 3).
Простота использования (easy to use):
- Ориентированность на задачи пользователя, не на функции программного продукта.
- Точность — изложение фактов, отсутствие ошибок (неточностей).
- Полнота — справка должна содержать все необходимое для применения пользователем программного продукта, только это и ничего кроме этого.
Простота изложения (easy to understand):
- Ясность — отсутствие двусмысленности и неясности. Изложенное должно быть понятно с первого раза.
- Конкретность — предметность (не абстрактность).
- Стиль — соблюдение единого стиля, использование стандартных формулировок, отсутствие ошибок: грамматических, пунктуационных, лексических и др.
Простота поиска (easy to find):
- Организация логической структуры изложения должна быть понятна пользователю (структурирование информации по типам, выделение главного и второстепенного, порядок изложения = порядок использования и др.).
- Возможность быстро и просто найти необходимую информацию (продуманное оглавление, навигация, поиск, ключевые слова, перекрестные ссылки, выделение информации и т.д.).
- Наглядность (скриншоты, схемы и другие иллюстрации, элемент комикса, выделение текста, значки и т.п.).
Каждый из пунктов требований подразделяется на подпункты, которые в целом составляют органичную и понятную картину качественной пользовательской документации. Эти и другие требования к качеству справки подробно разбираются в книге от IBM Press (смотрите выходные данные и ссылку в конце статьи).
Какой справка не должна быть
Учитывая сказанное выше, справку можно определить «от противного». Справка не должна ограничиваться описанием графического пользовательского интерфейса, команд и пунктов меню.
Вместо заключения приведу немного статистики, которая может быть интересна не только техническим писателям, но и заказчикам разработки ПО, инвесторам. По данным Лаборатории Касперского (доклад Большаковой М., Соболевской М. 2017), эффективность размещенной на сайте базы знаний по продуктам компании в 2017 году составила порядка 80%. Это доля вопросов, решенных в базе знаний, по отношению к общему числу решенных вопросов. 20% пришлось на звонки в службу поддержки и письменные вопросы. Иными словами, если убрать с сайта базу знаний, нагрузка на службу поддержки возрастет примерно в 5 раз. Таким образом, качественная пользовательская документация и справка на практике экономят значительные ресурсы и могут быть эффективными.
Подавляющее количество деловой документации, создаваемой на предприятии или поступающей в нее, содержат сведения о состоянии внутренних (внешних) дел юридических лиц.
Что такое информационно-справочные документы?
Подобные документы предназначаются для передачи сведений от одного адресата другому или для фиксирования информации.
В случае одобрения содержания документа проставляется резолюция руководителя, что служит основанием для принятия решений при выборе способа управленческого воздействия.
В информационно-справочных документах не содержатся поручения, нет обязательств по их выполнению. Особенность заключается в том, что они движутся снизу вверх по управленческой системе: от сотрудника к начальнику отдела, от руководителя отдела до главы компании, от подведомственного учреждения в вышестоящее.
Информационно-справочные документы объединяются назначением (вспомогательная направленность) и общим способом регистрации: отсутствует централизованная регистрация. Отдельные бумаги не регистрируются совсем, в остальных моментах за регистрацию отвечают авторы документов.
Вся документация информационно-справочного характера делится на составляющие части:
- входящие — письма, отчеты от головных предприятий, обособленных подразделений, обращения граждан;
- исходящие — отчеты о выполнении входящих запросов, инициативные и информационные письма, оформленные организацией;
- внутренние — служебные записки, отчеты, протоколы, подтверждающие деятельность компании.
В документооборот юридических лиц входят несколько видов информационно-справочных документов, различающихся своим назначением:
- докладная записка — составляется на имя директора (внутренняя), содержит факты, сведения, предложения по принятию управленческого решения, если направляется за пределы компании, считается внешней документацией;
- служебная записка — документ используется для передачи информации между структурными подразделениями (отделами);
- предложение — письменная инициатива сотрудников, направленная на внесение в действующий трудовой процесс предложений по его совершенствованию;
- объяснительная записка — адресуется руководителю учреждения и пишется от руки с подробным описанием проступка, внештатных ситуаций, нарушений трудовой дисциплины или служит приложением к главному документу, поясняющим отдельные пункты;
- заявление — личная просьба сотрудника или ходатайство о выявленных нарушениях должностных лиц (направляются на имя директора);
- представление — инициативно направленный документ по вопросам кадровых перестановок, награждения, материального стимулирования персонала;
- справка — подтверждает какие-либо факты служебного характера или события, удостоверяющие юридический факт (с места учебы, работы, о заработной плате, месте проживания);
- протокол — содержит последовательную запись процесса обсуждения насущных вопросов и принятия решений на совещаниях, конференциях, заседаниях постоянно действующих и временных коллегиальных органов;
- акт — составляется чаще комиссией (постоянно действующей или специально назначенной) и подтверждает установленное ее членами действие, отличается широким разнообразием по назначению и содержанию, иногда акт составляется одним или несколькими специалистами;
- расписка — подтверждает совершенное действие, как правило, получение денежных средств или материальных ценностей;
- доверенность — наделение полномочиями в письменном виде, выдаваемое руководителем специалисту для представления организации перед третьими лицами.
В организации могут возникать и иные виды информационно-справочной документации, главное, чтобы они отвечали основным требованиям: оперативное движение и их целенаправленное регулирование, однократность операций целевого значения, исключение лишних инстанций прохождения (все перемещения должны оправдываться деловой необходимостью).
Основные правила оформления и реквизиты
Главными моментами составления информационной или справочной документации являются:
- регистрация каждого документа с указанием даты и порядкового номера,
- обозначение автора документа (структурное подразделение, специалист),
- проставление визы руководства и подписи (в докладных и объяснительных записках автор и подписи аналогичны), иногда ставится печать.
Все указанные пункты влияют на силу документа с юридической точки зрения и государственного стандарта, обеспечивают его официальность и бесспорность.
На предприятиях внутренние документы печатаются на бланке с обозначением структурного подразделения (для служебной переписки). Бланки изготавливаются на листах формата А4.
Бланки используются строго по назначению и без подписи директора или его уполномоченного представителя не могут передаваться иным предприятиям, лицам.
При подготовке справочно-информационного документа должны соблюдаться принципы:
- структурирование текста (введение, изложение, заключение);
- краткость изложения при полноте информации;
- объективные и достоверные сведения.
Стиль служебных документов не допускает повторов и излишних подробностей, нейтрального тона повествования. В бумагах употребляется специальные термины, безличный характер изложения, исключаются заимствованные слова, имеющие аналог в русском языке.
Если в тексте используются наименования юридических лиц (полные или сокращенные), то они пишутся в строгом соответствии с учредительными документами.
Процедура принятия управленческих решений основана на обработке и сборе сведений о фактическом состоянии дел в системе управления в разных источниках/
В отличие от распорядительных справочно-информационные документы не требуют исполнения. Информация, содержащаяся в них, способна побудить к действию или только принята к сведению. Подобные бумаги являются основой для издания распоряжений по личному составу.
Читайте также: