Как сделать справочную систему
Cоздание справочной системы или руководства пользователя в Dr.Explain
Всем привет. Наверное, любой разработчик на вопрос, что вам больше всего не нравится в процессе разработки, ответит: «написание документации» или упомянет об этом в самом начале списка проблем. В документировании действительно ничего интересного нет, но, тем не менее, руководство пользователя, как я уже писал в своем первом посте на Хабре, является важным компонентом любого профессионального продукта. Плохо составленная документация будет не только препятствием на пути привлечения новых покупателей, но и является большим минусом к имиджу продукта и разработчика.
В то же время, программу с хорошей справочной системой почти наверняка купят. Несмотря на распространенное мнение о том, что руководство пользователя никто не читает, жизнь показывает обратное. Если пользователь купил многофункциональную программу, с которой никогда до этого не работал, то справка пользователя станет его настольной книгой, к которой он будет обращаться, чтобы быстрее освоить возможности программы и найти ответы на вопросы, возникающие при эксплуатации программы. Поэтому понятная, последовательная и лаконичная справка пользователя – это всегда большой плюс к положительному имиджу продукта и его потенциалу для получения прибыли.
Сам иногда занимаюсь help-файлами и не понаслышке знаю, что создание справочной системы занимает время и является кропотливой и нудной работой, особенно документирование интерфейса. Однако пару месяцев назад открыл для себя инструмент, который значительно ускоряет этот процесс. Речь идет о программе Dr.Explain от самарской компании Индиго Байт Системз. Она мне понравилась продуманным интерфейсом и возможностью документировать интерфейс ПО в полуавтоматическом режиме.
Dr.Explain vs. Help and Manual
Итак, Dr.Explain позволяет создавать help-файлы в формате CHM для поставки вместе с приложением, справочные системы в HTML для размещения на сайте продукта, а также руководства пользователя в RTF и в PDF с оглавлениями и ссылками. Справочная система генерируется в разных форматах из единого источника, что позволяет быстро обновлять документацию при выходе новых версий ПО. В этом плане Dr.Explain ничем не отличается от Help and Manual, которой я давно пользуюсь.
Интерфейс состоит из двух областей. Первая – это панель навигации с древовидной структурой содержания проекта. А вторая – редактор страниц.
В дереве задается вся структура help-файла, включая заголовки папок и страниц. Редактор страниц состоит из стандартных инструментов для написания и форматирования текста, а также имеются инструменты для вставки гиперссылок, картинок, таблиц и переменных. Все это есть и в Help and Manual, но панель инструментов в Dr.Explain скомпонована, на мой взгляд, более продуманно.
Рисунок 1. Панель инструментов Dr.Explain
Рисунок 2. Панель инструментов Help and Manual
Главная фишка Dr.Explain – это автоматизация самого трудоемкого процесса документирования – создание аннотаций пользовательского интерфейса. Да, вы правильно меня поняли. Больше не нужно делать снимки экрана самому, рисовать выноски и стрелки, вставлять все это хозяйство в проект вручную – программа сама сделает снимок любой части интерфейса по вашему выбору, проанализирует и найдет (сама!) все значимые элементы (кнопки, элементы управления, списки), вставит снимок в проект справки и автоматически расставит стрелки и пояснительные выноски к изображениям. Пользователю остается всего лишь ввести краткое пояснение к каждой выноске и все.
Кроме того, к выноскам можно добавить и более подробные пояснения. Для всех выносок программа автоматически сгенерирует симпатичную на вид табличку, которая будет размещаться ниже скриншота с выносками и может включать в себя все эти подробные пояснения.
Такое полуавтоматическое документирование интерфейса значительно ускоряет и облегчает создание справочной системы, т.к. разработчику остается всего лишь добавить свои описания в выноски. В Help and Manual я все это тоже могу сделать – правда, придется делать это вручную. Обычно я делаю снимки окон в Snagit, обрабатываю края снимка, добавляю тень, рисую стрелки. А для документирования элементов окна вручную создаю табличку, нарезаю снимки кнопок и контролов, обрабатываю их края и вставляю в проект, а затем пишу описания каждой выноски. На это тратится уйма времени и усилий.
Кое-что еще…
В Dr.Explain есть и другие полезные возможности, которых, к сожалению, нет в Help and Manual. Например, есть удобный режим просмотра проекта – одним кликом по соответствующей кнопке можно быстро посмотреть, как будет выглядеть справка в формате CHM или HTML после компиляции. Превью открывается прямо в окне редактора. Поверьте, это очень удобно. Однако нет PDF-превью – это минус. В Help and Manual чтобы посмотреть, как выглядит справка, нужно постоянно компилировать проект.
Также в программе есть возможность интегрировать контекстно-зависимую справку прямо в приложение (F1), управление деревом навигации, набор шаблонов оформления, поддержка CSS, возможность быстрого обновления документации при выходе новой версии программы путем замены иллюстраций, но с сохранением выносок, аннотаций, описаний; функция поиска и индексации в онлайн-справке без программирования (PHP, ASP) или баз данных на стороне сервера.
Дао разработки справочной документации для IT-продукта
Любите читать хелпы? А писать? Думаю, что 99% из вас ответят “НЕТ”.
Но от создания справки никуда не денешься, ведь справка является обязательным средством общения с пользователем. А чтобы создание хелпов не оказалось чем-то сложным, неуправляемым и непонятным, необходимо построить чёткий и отлаженный процесс.
В этой статье я бы хотел поделиться нашим опытом и описать процесс создания справочной документации, который мы используем в Alconost.
В идеальном случае (в больших компаниях так и есть) все эти роли представлены отдельными сотрудниками, но в суровой реальности все эти шапки может носить одновременно один человек.
Для того чтобы работа над справочной документацией (а это не только создание, но и дальнейшая поддержка и развитие) не тормозила процесс разработки, роли разработчика и технического писателя должны быть разделены.
Сами vs. аутсорс
Если у вас большая компания, много продуктов и есть чем загрузить технического писателя на 100%, оптимально будет найти или вырастить технического писателя. Следует учесть, что технический писатель — это достаточно редкая профессия; эти люди всегда имеют много хорошей работы и редко ее ищут, т.е. отделу кадров придется поднапрячься.
Альтернативный вариант — аутсорсинг создания справочной документации. В этой модели разработчик оставляет за собой только свою собственную роль. А менеджер проекта по созданию и поддержке справочной документации, техписы, редакторы, переводчики предоставляются подрядчиком. Благодаря тому что подрядчик делает справку для множества клиентов, его технические писатели всегда загружены, есть ресурсы и интерес для обучения новых.
Отдельно стоит упомянуть и инструменты создания справки. Не всегда для разработчика оправдана покупка программных систем для создания справочной документации. Если у вас небольшая утилита, и нужен лишь Getting Started, не стоит заморачиваться с покупкой дорогостоящего софта.
Отдавать разработку справки на аутсорсинг полезно еще по одной причине. Внешние технические писатели могут найти баги, посоветовать разработчику некоторые улучшения в интерфейсе или предложить собственные идеи по развитию программы. Этот пристальный (а технический писатель изучает программу глубже обычного пользователя) “взгляд со стороны” никогда не окажется лишним. Разработку справочной документации может считать дополнительной стадией QA.
Требования к результату
Не важно, своими силами или силами аутсорсера вы будете делать справку, на первом этапе вам потребуется четкое представление о том, что собственно нужно. Справка бывает разная, я писал об этом в прошлой статье Виды и форматы справок (инфографика) — выберите, что вы хотите в качестве конечного результата.
Процесс
Проекты по разработке справки обычно достаточно длительные по времени, поэтому вам также понадобится инструмент контроля и управления: вы должны всегда иметь возможность видеть на каком этапе все застряло, какой следующий шаг, сроки, стоимость.
Менеджер проекта по созданию справочной системы является “двигателем” всего процесса. В его задачи входит планирование, контроль промежуточных результатов, обеспечение коммуникации между всеми участниками проекта.
1. Бриф
Даже если вы собираетесь писать справку самостоятельно, сперва будет неплохо ответить себе на ряд важных вопросов о продукте. А если справку вы заказываете на стороне — будет странно, если вам эти вопросы не зададут.
Этот документ (бриф) послужит своего рода ТЗ для технического писателя. В процессе заполнения вы точно определяетесь с требованиями к формату справки, примерным объёмом текста, целевой аудиторией, языками, уровнем подготовленности пользователя и т.д.
2. Содержание
Правильно составленное содержание — это половина дела. Если материал справки хорошо структурирован, ваши пользователи найдут нужную информацию за пару кликов. Не спешите сразу же писать текст, лучше детально проработайте иерархию и уровни вложенности топиков.
Для работы со структурой справки можно использовать простой spreadsheet. По ходу составления содержания вы сможете определиться с обязательными для упоминания моментами, ключевыми словами (онлайн-хелп на сайте послужит и для SEO), количеством и содержанием скриншотов, приблизительным объёмом текста. На этом этапе можно оценить сроки и бюджет проекта.
Содержание составляется техническим писателем и утверждается разработчиком. После того как содержание утверждено, технический писатель приступает к написанию текста топиков.
3. Оформление хелпа
Общее оформление справки может как отпугнуть пользователя, так и наоборот, показать, что для разработчика важна каждая мелочь. Если бюджет позволяет, а душа требует прекрасного, то наймите для этой задачи дизайнера. Вы должны определиться с шаблонами и стилями страниц для всех форматов справки, выбрать разрешение и тему скриншотов. Небольшой хинт: чёрный текст (а для любителей яблок — серенький и синенький ) на белом фоне всегда смотрится аккуратно и профессионально, поэтому не спешите напихать в оформление кучу цветов, стилей и прочих украшений.
Все работы по оформлению ведите параллельно и независимо от написания текста. Так вы сэкономите время и быстрее получите пилотный вариант справки.
4. Контроль промежуточных версий
Условно поделите справку на несколько частей и попросите технического писателя присылать промежуточную версию справки после завершения каждой части. Все корректировки по тексту, содержанию и оформлению делайте на как можно более ранних стадиях проекта — таким образом писатель сможет учесть ваши замечания и комментарии при создании последующих текстов.
Если вы пишете текст самостоятельно, попросите сторонних людей оценить промежуточные результаты работ. Как показывает практика, это бывает очень полезно.
5. Финальная версия
Когда все топики уже написаны, сделайте небольшую паузу, чтобы отвлечься и посмотреть на результат свежим взглядом. Вдруг вы что-то упустили? А может надо что-нибудь сократить?
Прочтите получившийся хелп целиком и внесите последние правки.
6. Вычитка (пруфридинг)
Я рекомендую отдавать текст справки на вычитку профессиональному редактору. Грамотный текст и отсутствие опечаток и ошибок повышают доверие пользователей к компании и авторитет разработчика.
7. Экспорт документации
После внесения всех правок редактора и настройки оформления сделайте финальный экспорт проекта справки во все необходимые форматы. И обязательно сохраните проекты справки, иллюстрации и все исходники в файловом хранилище, чтобы при апдейте не рвать волосы на голове из-за потерянных исходников.
Инфраструктура
Для хранения проектов справки, иллюстраций и исходных данных я рекомендую использовать облачные хранилища данных с возможностью многопользовательской работы и контролем версий (dropbox, box.com), а так же онлайн-документы (googe docs, office360).
Финал
После завершения работы над справкой разместите хелп в интернете, напечатайте руководство или интегрируйте контекстную справку в программу. Но это далеко не конец. Следующий этап — апдейт хелпа или перевод. Именно про эти задачи я расскажу в следующих постах.
А пока жду от вас комментариев, предложений и вопросов. Как справочную документацию пишете вы?
Alconost занимается локализацией приложений, игр и сайтов на 60 языков. Переводчики-носители языка, лингвистическое тестирование, облачная платформа с API, непрерывная локализация, менеджеры проектов 24/7, любые форматы строковых ресурсов.
Мы также делаем рекламные и обучающие видеоролики — для сайтов, продающие, имиджевые, рекламные, обучающие, тизеры, эксплейнеры, трейлеры для Google Play и App Store.
Как сделать справочную систему
При разработке программы хорошим тоном является снабжение этой программы справочной системой. И чем сложнее программа, тем более необходимой оказывается справочная система.
Имеется много различных способов и средств для разработки справки. Рассмотрим один из них — это разработка справочной системы в виде файла с расширением chm при помощи бесплатной программы HTML Help Workshop фирмы Microsoft.
Формат CHM ( Compiled HTML — скомпилированный HTML) широко используется фирмой Microsoft для создания справочных файлов к своим продуктам.
При разработке справочной системы есть смысл придерживаться следующего порядка:
продумать общую схему справочной системы, т.е. какие темы должны быть отражены в справке;
написать все тексты по пунктам справки. Использовать лучше обычный текстовый редактор, например Writer из OpenOffice.org (OOO);
Рассмотрим последний пункт более подробно.
Создание нового проекта
Создать новый проект очень просто. Рассмотрим этот процесс по шагам:
Запускаем программу HTML Help Workshop:
Сохраним файл проекта.
Добавление новых файлов справки
Теперь в основном окне вкладки Project кроме секции [OPTIONS] появилась секция [FILES] с перечнем тех файлов, что мы только-что выбрали:
Создание оглавления
После того, как все файлы справки добавлены в проект, можно приступить к созданию оглавления. Выполним следующие действия:
Теперь самое важное: необходимо связать пункты оглавления с соответствующими им файлами справки (для «книги» это не всегда требуется, а для «страницы» это обязательно).
И так последовательно заводим всё оглавление. Как видим, всё достаточно просто.
Редактирование оглавления
Выделив необходимый пункт оглавления, его можно отредактировать.
Прежде всего, необходимо убедится в правильности следования пунктов оглавления. Для перестановки вверх служит кнопка Move selection up ( Переместить выделенное вверх ), для перестановки вниз — Move selection down ( Переместить выделенное вниз ).
Затем с помощью кнопок Move selection right ( Переместить выделенное вправо ) и, при необходимости, — Move selection left ( Переместить выделенное влево ), определяем вложенность пунктов оглавления.
Пример того, что может получиться.
А вот так справочная система будет выглядеть в работе:
Выходной файл будет иметь имя HelpAlfa.chm.
Создание предметного указателя
Предметный указатель, по своей сути, является альтернативой оглавлению. Есть смысл создавать предметный указатель только в том случае, когда справочная система велика, и поиск по оглавлению получается долгим.
Порядок создания предметного указателя аналогичен порядку создания оглавления. Рассмотрим это по шагам:
В открывается окне диалога Сохранить как задаём имя индексного файла. Можно согласиться с тем, что идёт по-умолчанию: Index.hhk. Окно проекта будет выглядеть так:
На вертикальной панели инструментов щёлкаем по второй сверху кнопке — Inset a keyword ( Вставить ключевое слово ). На экране появится окно Index Entry ( Вход указателя ).
В поле Keyword ( Ключевое слово ) набираем необходимое ключевое слово, например, «Функции». Именно в таком виде это слово будет показываться во вкладке Указатель панели навигации справочника.
Таким же образом заполняем информацию для остальных ключевых слов.
Редактирование предметного указателя
Предметный указатель можно упорядочить — кнопка Sort keywords alphabetically ( Сортировать в алфавитном порядке ).
Есть и другие возможности по редактированию предметного указателя, но на них мы не останавливаемся.
Подключение файла со справочной системой к программе на C#
Разработка справочной системы, отладка
2.1. Справочная система
Далее следует создать главу справки, посвященную документу. Для того чтобы перейти к окну редактирования справочной информации, нужно нажать на кнопку Справочная информация, которая расположена на той же вкладке Прочее.
Документ автоматически сохраняется при закрытии.
Мы ввели в документ руководство по использованию документа, теперь посмотрим, как получить доступ к справке по документу из режима 1С:Предприятие.
Как уже было сказано, при установке флажка Включать в содержание справки, глава, посвященная документу, становится доступной из общей справки к программе, вызываемой из меню Справка>Справка, рис. 2.3.
А именно, здесь, в дополнение к уже существующему стандартному разделу 1С:Предприятие, появляется раздел Конфигурация, который содержит нашу справку.
Получить доступ к этой информации можно и из окна документа Начисление зарплаты или из окна списка этих документов, рис. 2.4.
Пользователь нашей конфигурации сможет получить доступ к этому разделу справки, воспользовавшись системой поиска по справке. Для этого ему нужно будет выполнить команду главного меню программы Справка>Поиск по справке и ввести в окно поиска ключевые слова, которые, по его мнению, должны привести к справке, посвященной документу Начисление зарплаты, рис. 2.6.
2.2. Автоматизация заполнения регистра сведений
Создадим новую обработку, назовем ее ЗаполнениеГрафиков.
На вкладке Данные добавим следующие реквизиты:
Создадим форму обработки, укажем, что реквизитам формы должны соответствовать поля ввода, рис. 2.7.
Теперь введем код, который будет выполняться при нажатии на кнопку Выполнить.
Рассмотрим особенности этого кода.
Переменная ТекущаяДата будет использована в цикле при заполнении реквизита Дата записи регистра.
Переменная ДлинаСутокВСекундах применяется для хранения количества секунд в сутках. На это значение будет увеличиваться переменная ТекущаяДата в цикле.
Заполнение реквизитов Дата и График записи регистра вряд ли вызовет дополнительные вопросы. А вот заполнение реквизита РабочийДень потребует некоторых объяснений.
Здесь мы используем сокращенную форму записи оператора Если. Его можно расшифровать следующим образом: ЕСЛИ(УСЛОВИЕ, ТОГДА, ИНАЧЕ).
Команда ТекущаяДата = ТекущаяДата+ДлинаСутокВСекундах позволяет перейти к следующему дню и цикл повторяется.
Проверим правильность работы только что созданной обработки. Прежде чем запускать ее, уточним, верно ли заполнен реквизит Примечание для каждого из графиков, рис. 2.8.