Перевод, локализация и изготовление видеороликов
41,69
рейтинг
29 ноября 2012 в 14:00

Разработка → Виды и форматы справок

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

К нам в 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

Надеюсь, что мы помогли вам определиться с этим нелегким выбором. Ждем ваших вопросов и предложений!
Автор: @alconost
Alconost, Inc.
рейтинг 41,69
Перевод, локализация и изготовление видеороликов

Комментарии (38)

  • 0
    Очень интересная информация, спасибо. Вопрос о справочной документации для меня на данный момент очень актуален. Не думал, что существуют компании специализирующиеся на подобных услугах.
  • +4
    «Для вас важно качество» → «Нет» → «Wiki» — это как вообще?
    FAQ — это если не срочно, а Getting Started — срочно. Каша какая-то.
    • 0
      Тут имеется в виду, что wiki пишут и редактируют сами пользователи. Поэтому отсутствует единый стиль, и возможны ошибки и неточности. Но если wiki будет редактироваться командой технических писателей, то качество, конечно, не пострадает.
      • +2
        Выходит, в одном месте один критерий, в другом другой, в этом конкретном случае критерий — источник информации, но вы его называете «экономия» или «качество». Примерно это я и называю кашей. По вашей схеме невозможна ситуация, когда компания использует wiki, но наполняют её сотрудники; или ситуация, когда экономить компания не хочет и всячески поощряет качественный вклад, и наполняют все — и пользователи, и сотрудники, и т.д…
        • +3
          «Вики, которое заполняется сотрудниками» — это в системе ценностей автора статьи скорее «online help», а не «wiki». Online help можно делать на чём угодно. Можно весь сайт делать на вики, но давать права редактирования только сотрудникам — сайт от этого, ИМХО, «вики» не станет, даже если использовать вики-движок.
        • +1
          Мне кажется Вы придираетесь. Схема вполне понятна и читаема.
          И, да, вики всё таки уступает по качеству хотя бы тем, что выглядит не особо презентабельно кто бы её ни наполнял. Кроме того, не совсем на это она ориентирована и что бы там в итоге не оказалось, это будет обычная база знаний и не более того.
          • 0
            уступает по качеству хотя бы тем, что выглядит не особо презентабельно

            Чему уступает-то? Вы понимаете, что тёплое с мягким сравниваете? Не говоря о том, что сам тезис «wiki выглядит не особо презентабельно» я подвергаю сомнению (это если предположить, что вы имеете ввиду конкретный шаблон интерфейса — самым распространённым является стандартный шаблон Wikipedia, потому что если нет, то тогда вообще непонятно, что вы имеете ввиду).

            И вы так говорите «база знаний», как будто это что-то плохое =)
          • +1
            +1 к IIIEB4YK. То, что непрезентабельно — бред номер один. MediaWiki + расширения => можно отменной красоты навертеть (мы у себя 75 расширений используем [сборка mediawiki4intranet], а Wikimedia вообще аж ~140). Без расширений, конечно, менее красиво.

            Аналогично, если вы просто поставите движок и, ничего больше не делая, будете думать, что тут же прибегут пользователи и всё за вас напишут — то да, будет некачественно. :-) Но если самим активно заниматься наполнением — вики-системы для документирования круты, потому что легко вносить изменения.

            Так что нужно как минимум уточнять, кто её будет наполнять. :-)
            • +1
              Что-то я уже сам начал путаться и других запутывать. Извините.
  • +4
    Help & Manual, а потом хоть pdf, хоть chm, html или word :)
  • 0
    А диаграммки вы где рисовали такие? Случайно не в Gliffy.com?
    • 0
      Глаз-алмаз) Да, именно Gliffy.
      Довольно удобно, правда вчера и сегодня в Хроме текстовые надписи стали невидимыми.
  • 0
    Картинки в чем рисовали?
    • 0
      Смотрите предыдущий комментарий.
  • 0
    А есть ли специализированные сервисы, заточенные под написания справок?
    • 0
      Вы имеете в виду редакторы справки, позволяющие работать в облаке?
      Или компании, которые вам напишут мануал?
      • 0
        Редакторы справок on-line.
          • 0
            из параллельной области, но вдруг видели — есть ли такие гибриды вики и doxygen/PHPDoc/Javadoc? То есть редактирование документации кода из вики-сайта с push-ем в репозиторий
            • 0
              Возможно, я Вас не так понял, но посмотрите readthedocs.org
              • 0
                эмм, кажется, это не то.
                Вот есть у меня документация к коду с описанием классов и функций (генерируется из кода), типа такой:
                semantic-mediawiki.org/doc/
                Хочется иметь кнопочку Edit, которая бы позволила поправить эти описания, а эти поправки бы закоммитились в исходный код.
        • 0
          Semantic MediaWiki — если нужна мощь и перестраивание контента
          DokuWiki — если самое важное — это простой синтаксис
  • 0
    Извиняюсь, дубль
  • +2
    Еще можно добавить, что для компиляции справки .chm для языков, отличных от английского, нужно использовать специальный хак: www.steelbytes.com/?mid=45

    Компилятор делался майкрософтом более десяти лет назад, еще в доюникодные времени, и языки, отличные от английского, воспринимает… забавно.
    • 0
      Подробнее можно?
      А то по ссылке лишь фраза «a command line clone of Microsoft AppLocale :-)» и ссылка для скачивания…
      • +1
        Конечно. Набираем в гугле «applocale chm» без ковычек и видим много инструкций и описаний самой проблемы, например вот:

        www.it-authoring.com/bb/helpauth/viewtopic.php?f=22&t=9713

        • 0
          Спасибо
  • 0
    Правильная справка должна быть контекстной, встроенной в интерфейс, без перехода «в справку».
    • +3
      Если интерфейс перегружен элементами, то повсеместная контекстная справка будет последним гвоздём в крышку его гроба.
      • 0
        Ну так необязательно всё завешивать вопросиками (image), можно, скажем, на F1 открывать overlay, в котором что-то подписано и т.п. Или окошко, в котором в свободном виде можно задать вопрос, при этом учитывается текущий контекст (если я в меню Икс, и спрашивают об Игрек, то более релевантными результатами считаются «Икс+Игрек»).
  • 0
    Wiki — некачественно, но экономно. Не согласен, это скорее уж «голая вики»
  • 0
    Для устранения проблем с открытием CHM файлов, загруженных из сети, можно использовать бесплатную утилиту HHReg.
    Я вообще открываю контекстное меню такого файла и ставлю галочку, что его можно просматривать.
    Но тот факт, что в майкрософте заставляют пользователей вот так делать говорит о том, что скорее всего этот формат отправят в историю со временем.

    EXE (e-Book) — исполняемый Windows файл. Плюсы: не требуется дополнительное ПО для просмотра.
    Вот тут не понятно — что такое дополнительное ПО. Для CHM и HTML тоже не нужно дополнительное ПО, не входящее в стандартную поставку операционной системы. Ну а вообще многие такой хелп даже побоятся открывать. Даже дистрибутивы для виндовса часто поставляют не как exe файлы, а как msi пакеты. Возможно о таком формате даже упоминать не стоило.
    • 0
      > Но тот факт, что в майкрософте заставляют пользователей вот так делать говорит о том, что скорее всего этот формат отправят в историю со временем.

      Как бы туда MS на отправили, со временем-то. Любят они форматы придумывать и забывать — это придает им уверенность, что они не просто на гребне прогресса, но и сами по себе этот гребень создают.
      Заставлять юзеров делать что-то лишнее — не самое мудрое. Лучше бы обезопасили формат в смысле замены движка вывода на что-то более надежное и недырявое, чем ядро IE.

      Самое же неприятное, что де-факто документацию чаще всего делают либо в (не побоюсь, убогом, с точки зрения работы с текстом) .pdf-е, либо в .html (плюс папочка с css и изображениями), либо в .rtf/.ods — больше-то ничего кроссплатформенного, да еще и открывающегося у всех, нет. MS, вместо чем выпустить недырявое ПО для просмотра .chm под все ОСи вокруг, старательно забыло про него, так что неплохой (по идее своей) формат так и не стал «наименьшим общим знаменателем». Жаль.
      • 0
        CHM не может стать наименьшим общим знаменателем, потому что мелкомягкие с каждой версией винды, с каждой версией вижуал студии выдумывают по новому формату справки.

        HLP: WinHelp (на базе извращений с RTF, был запуск приложений с помощью кнопок и прочие прелести...) — выпилили почти полностью.
        Где-то там в промежутке эксперименты с конвертацией из HTML…
        CHM: HTML Help (HTML с картинками и всякими индексами в архиве) — из-за какой-то «уязвимости» стало нужным запихивать в архив при выкладывании в Сети.
        HXS: Microsoft Help 2
        MSHC: Microsoft Help Viewer aka Microsoft Help 3 (выпилили индексы, «оно само как-нибудь» — теперь установка не «мержит» справку по два часа, а индексирует по два часа — технологический прорыв)
  • +3
    Консольное приложение для *Linux, *BSD, *nix? -> man
    • 0
      Не всё так просто :)
      man скорее соответствует getting started или короткой справке, иначе лучше GNU info, соответствующий user manual. Хотя бы из-за гиперссылок.

      Ну и про вывод ещё более короткой справки чем man при указании ключика -h или --help забывать не нужно. Производит впечатление сырого ПО, если они не работают. Конкретно на меня даже графическое ПО, не выводящее справку на -h (например, Skype) производит впечатление сырого и не предназначенного для конечного пользователя.
  • 0
    Надо еще приписать — «и обновлять справку постоянно!» И обязательно указывать, для какой версии подходит описание, и когда (дата) оно написано.

    А то хуже нет, когда что-то надо срочно найти/сделать, а документация на официальном сайте содержит описание функционала и настроек позапрошлой major версии, да еще с припиской, что вообще оно работает глючно и лучше не пользоваться. Тогда как в нынешней ветке не только все доточили, но оно и десяток новых опций приобрело.
  • 0
    О качестве вашей работы можно судить по наглядности материала.
    Я не оцениваю содержимое, а именно оформление и доступность.
    Молодцы!

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

Самое читаемое Разработка