Привет, Хабр!

К нам в Alconost часто приходят клиенты и говорят "Мне нужна справочная система для моей программы. Сделайте мне ПэДээФку”. Мы создаем руководство пользователя, оформляем PDF, а потом оказывается, что на самом деле нужна была контекстная справка с индексом и поиском.

Именно поэтому хотелось бы поделиться со всеми простыми схемами и описанием видов и форматов справки.





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

Виды справок

Мы разделили справки на следующие виды по назначению:

• Руководства и инструкции пользователя (оператора, программиста, администратора) — классические справочные документы, которые содержат набор инструкций и описание функционала ПО в зависимости от квалификации пользователя. Предназначены в основном для печати (имеют бумажный вариант).
• Quick start (Быстрый старт), Getting started (С чего начать) — небольшие (до 10 листов) руководства, цель которых — быстро научить пользоваться продуктом и получить конечный результат. Могут создаваться, пока ещё нет полного руководства, или могут быть частью большого хелпа (со ссылками на соответствующие подробные описания).
• Online help, WebHelp (Онлайн справка) — хелп, который доступен на сайте производителя. Обычно выполнен в стиле сайта. Очень удобен, так как не нужно сохранять его на локальном диске, в него встроен поиск и кейворды. Онлайн справка помогает улучшить SEO.
• Wiki (вики) — веб-сайт, структуру и содержимое которого пользователи могут самостоятельно изменять с помощью инструментов, предоставляемых самим сайтом. Плюсы: пользователи сами пишут хелп. Минусы: необходимо изучить вики-разметку, возникают сложности при установке wiki-движка.
• Статьи «How to...» — статьи (или разделы справки), направленные на решение одной конкретной задачи (пример "Как расшарить USB устройство для компьютеров в локальной сети?”). Как правило, такие статьи содержат конкретную последовательность действий с несколькими скриншотами, описанием возможных проблем и их решением. Данные тексты можно использовать для размещения в сети (включая в них кейворды), что способствует продвижению продукта. В конце статьи How to можно разместить обучающее видео.
• FAQ (ЧАВО) — вопросы и ответы на них; часто располагаются в конце справки после раздела Troubleshooting. Если предвосхитить большинство таких вопросов и раскрыть их в справке, то можно существенно снизить нагрузку на службу поддержки. Данный раздел рекомендуется постоянно обновлять, основываясь на письмах и отзывах пользователей.
• EULA (Лицензионные соглашения), Terms of Service (Условия использования), Privacy Policy (Политика конфиденциальности) — разделы справочной документации, которые регулируют юридические отношения между производителем и пользователем, устанавливают ответственность сторон, а также указывают авторские права. Лучше доверить написание этих текстов юристу, чтобы он избавил вас от ответственности за то, что с помощью вашей программы взломали сеть Пентагона.

Форматы справок

В зависимости от вида справки и места её размещения выбирается один или несколько форматов:

• DOC (RTF) — Распространённый формат для документации. Если хотите открывать справку на любой платформе и импортировать в различные редакторы, то переведите её в формат RTF.
• HTML — Формат для онлайн-хелпа. Его можно также открывать на локальном компьютере. Обычно онлайн-хелп представляет собой директорию с HTML, CSS и JS файлами.
• CHM Данный формат предназначен в основном для контекстной справки Windows-приложений (F1), CHM документ состоит из сжатых HTML страниц и иллюстраций. Для устранения проблем с открытием CHM файлов, загруженных из сети, можно использовать бесплатную утилиту HHReg.
• PDF — Формат справки, использующийся для печати. При экспорте в данный формат необходимо обращать внимание на шрифт CID (лучше ставить Unicode), сжатие текста (максимальное) и формат рисунков, иначе конечный PDF файл будет иметь слишком большой размер.
• EXE (e-Book) — исполняемый Windows файл. Плюсы: не требуется дополнительное ПО для просмотра. Минусы: может содержать вирусы, не так хорош для печати, как PDF; не просматривается на Mac.
• HXS (MSHC) — форматы справки для Visual Studio (движки MS Help 2 и MS Help 3). Файлы представляют собой zip-архивы с html файлами и изображениями. Используются в основном для документирования кода.
• ePUB — формат справки, предназначенный для мобильных платформ (iOS, Android, букридеры различных производителей). Для просмотра хелпов в формате ePUB на ПК можно пользоваться бесплатной утилитой Adobe Digital Editions.

Как выбрать вид и формат хелпа?

Ознакомьтесь с вышеперечисленными описаниями и схемами и ответьте себе на 2 главных вопроса: "Кто будет читать мою справку?”, "Где (и на чём) ее будут читать?”. И все сразу станет на свои места.

А вот и несколько примеров справочных материалов различных видов: alconost.com/help#examples

Надеюсь, что мы помогли вам определиться с этим нелегким выбором. Ждем ваших вопросов и предложений!