Введение
Качество справочной системы для конечного пользователя определяется не только наличием контента, но и тем, насколько легко его найти — через дерево содержания, поиск по ключевым словам или полнотекстовый поиск. В статье подробнее разберём, как продумать структуру TOC (Table of Contents) и индекса ключевых слов для реальной, не игрушечной справки с несколькими десятками страниц, и какие практики делают навигацию по справке удобной.
Концепция
TOC в .qhp — иерархическое дерево, обычно отражающее логическую структуру материала (разделы → подразделы → конкретные темы), и его глубина и группировка должны соответствовать тому, как пользователь мысленно категоризирует задачи, а не структуре исходного кода приложения. Индекс ключевых слов — отдельный, «плоский» механизм: каждое ключевое слово ссылается на одну или несколько страниц, и пользователь, знающий специфичный термин (например, название конкретной функции или настройки), может найти нужную страницу напрямую, минуя навигацию по дереву.
Полнотекстовый поиск Qt Help Framework строит индекс автоматически на основе текстового содержимого всех HTML-страниц, перечисленных в <files> — в отличие от TOC и keywords, для него не нужна ручная разметка, но качество результатов поиска прямо зависит от того, насколько содержательно и без избыточного «шума» (навигационные элементы, повторяющиеся колонтитулы) написан сам текст страниц.
Пример кода: Разметка контента справки
<!-- Фрагмент .qhp с более развитой структурой TOC и keywords для реальной справки -->
<toc>
<section title="MyApp — Справка" ref="source/index.html">
<section title="Начало работы" ref="source/getting_started.html">
<section title="Системные требования" ref="source/getting_started.html#requirements" />
<section title="Установка" ref="source/getting_started.html#install" />
<section title="Первоначальная настройка" ref="source/getting_started.html#setup" />
</section>
<section title="Работа с документами" ref="source/documents.html">
<section title="Создание нового документа" ref="source/documents.html#new" />
<section title="Импорт из других форматов" ref="source/documents.html#import" />
<section title="Экспорт и печать" ref="source/documents.html#export" />
</section>
<section title="Настройки приложения" ref="source/settings.html">
<section title="Общие настройки" ref="source/settings.html#general" />
<section title="Настройки сети" ref="source/settings.html#network" />
</section>
<section title="Часто задаваемые вопросы" ref="source/faq.html" />
</section>
</toc>
<keywords>
<!-- Один пользовательский термин может вести на несколько релевантных страниц -->
<keyword name="импорт" ref="source/documents.html#import" />
<keyword name="импорт CSV" ref="source/documents.html#import" />
<keyword name="экспорт" ref="source/documents.html#export" />
<keyword name="прокси-сервер" ref="source/settings.html#network" />
<keyword name="proxy" ref="source/settings.html#network" /> <!-- синоним на латинице -->
<keyword name="печать" ref="source/documents.html#export" />
</keywords>
<!-- documents.html — пример содержательного, "чистого" для индексации текста -->
<h2 id="import">Импорт из других форматов</h2>
<p>
MyApp поддерживает импорт документов из CSV, XLSX и устаревшего формата DOC.
Чтобы импортировать файл, выберите пункт меню «Файл → Импорт» и укажите
путь к исходному файлу. Поддерживаемые кодировки текста: UTF-8, Windows-1251.
</p>
Пояснения к коду
Расширенный TOC группирует страницы по функциональным областям приложения (документы, настройки), а не по техническим модулям кода — пользователь ищет «как импортировать файл», а не «класс ImportManager», и структура справки должна отражать первый, а не второй взгляд на задачу. Раздел «Часто задаваемые вопросы» вынесен на верхний уровень TOC отдельно — это распространённый паттерн, облегчающий доступ к самым частым вопросам без необходимости угадывать, в какой раздел иерархии они могли бы логически попасть.
Дублирование ключевых слов с синонимами ("прокси-сервер" и "proxy") в индексе — намеренный приём: пользователи ищут одно и то же понятие разными терминами (русский/английский, формальный/разговорный), и индекс должен учитывать это явно, поскольку Qt Help Framework не выполняет никакой автоматической нормализации синонимов.
Подводные камни
- TOC, слепо копирующий структуру кода или внутренней архитектуры продукта. Разделы вида «Модуль NetworkManager» или «Класс DocumentImporter» в пользовательской справке создают барьер для непрограммиста — структура навигации должна соответствовать менталу пользователя («что я хочу сделать»), а не внутренней архитектуре разработки.
- Слишком глубокая иерархия TOC (четыре-пять уровней вложенности для простых тем) усложняет навигацию — пользователю приходится разворачивать множество уровней дерева, чтобы добраться до искомой темы; для большинства справок двух-трёх уровней вложенности достаточно.
- Текст страниц, написанный с обилием навигационного «шума» (повторяющиеся на каждой странице меню, колонтитулы, ссылки «Смотрите также» без содержательного текста) ухудшает релевантность полнотекстового поиска — поисковый индекс не отличает основной контент от навигационной обвязки, и избыточный шум «размывает» релевантные результаты.
- Отсутствие ключевых слов для самых частых запросов пользователей. Если индекс ключевых слов составлен формально, по названиям разделов TOC, а не по реальным терминам, которые пользователи вводят в поиск (что можно узнать из обращений в поддержку или аналитики использования встроенного поиска), индекс не выполняет свою главную функцию — быстрый прямой доступ к нужной информации по знакомому пользователю термину.