Привет!
Любите читать хелпы? А писать? Думаю, что 99% из вас ответят “НЕТ”.
Но от создания справки никуда не денешься, ведь справка является обязательным средством общения с пользователем. А чтобы создание хелпов не оказалось чем-то сложным, неуправляемым и непонятным, необходимо построить чёткий и отлаженный процесс.
В этой статье я бы хотел поделиться нашим опытом и описать процесс создания справочной документации, который мы используем в Alconost.
Роли
- Разработчик (программист или продакт менеджер);
- Технический писатель;
- Менеджер проекта.
В идеальном случае (в больших компаниях так и есть) все эти роли представлены отдельными сотрудниками, но в суровой реальности все эти шапки может носить одновременно один человек.
Для того чтобы работа над справочной документацией (а это не только создание, но и дальнейшая поддержка и развитие) не тормозила процесс разработки, роли разработчика и технического писателя должны быть разделены.
Самозанятость / Как ОФОРМИТЬ САМОЗАНЯТОСТЬ за 5 минут / Приложение МОЙ НАЛОГ
Сами vs. аутсорс
Если у вас большая компания, много продуктов и есть чем загрузить технического писателя на 100%, оптимально будет найти или вырастить технического писателя. Следует учесть, что технический писатель — это достаточно редкая профессия; эти люди всегда имеют много хорошей работы и редко ее ищут, т.е. отделу кадров придется поднапрячься.
Альтернативный вариант — аутсорсинг создания справочной документации. В этой модели разработчик оставляет за собой только свою собственную роль. А менеджер проекта по созданию и поддержке справочной документации, техписы, редакторы, переводчики предоставляются подрядчиком. Благодаря тому что подрядчик делает справку для множества клиентов, его технические писатели всегда загружены, есть ресурсы и интерес для обучения новых.
Отдельно стоит упомянуть и инструменты создания справки. Не всегда для разработчика оправдана покупка программных систем для создания справочной документации. Если у вас небольшая утилита, и нужен лишь Getting Started, не стоит заморачиваться с покупкой дорогостоящего софта.
Отдавать разработку справки на аутсорсинг полезно еще по одной причине. Внешние технические писатели могут найти баги, посоветовать разработчику некоторые улучшения в интерфейсе или предложить собственные идеи по развитию программы. Этот пристальный (а технический писатель изучает программу глубже обычного пользователя) “взгляд со стороны” никогда не окажется лишним. Разработку справочной документации может считать дополнительной стадией QA.
Требования к результату
Итак, ближе к делу.
Не важно, своими силами или силами аутсорсера вы будете делать справку, на первом этапе вам потребуется четкое представление о том, что собственно нужно. Справка бывает разная, я писал об этом в прошлой статье Виды и форматы справок (инфографика) — выберите, что вы хотите в качестве конечного результата.
6 ошибок самозанятых: как не потерять весь доход за 3 года. Штрафы для самозанятых в 2022 году. НПД.
Процесс
Проекты по разработке справки обычно достаточно длительные по времени, поэтому вам также понадобится инструмент контроля и управления: вы должны всегда иметь возможность видеть на каком этапе все застряло, какой следующий шаг, сроки, стоимость.
Менеджер проекта по созданию справочной системы является “двигателем” всего процесса. В его задачи входит планирование, контроль промежуточных результатов, обеспечение коммуникации между всеми участниками проекта.
1. Бриф
Даже если вы собираетесь писать справку самостоятельно, сперва будет неплохо ответить себе на ряд важных вопросов о продукте. А если справку вы заказываете на стороне — будет странно, если вам эти вопросы не зададут.
Этот документ (бриф) послужит своего рода ТЗ для технического писателя. В процессе заполнения вы точно определяетесь с требованиями к формату справки, примерным объёмом текста, целевой аудиторией, языками, уровнем подготовленности пользователя и т.д.
2. Содержание
3. Оформление хелпа
Общее оформление справки может как отпугнуть пользователя, так и наоборот, показать, что для разработчика важна каждая мелочь. Если бюджет позволяет, а душа требует прекрасного, то наймите для этой задачи дизайнера. Вы должны определиться с шаблонами и стилями страниц для всех форматов справки, выбрать разрешение и тему скриншотов. Небольшой хинт: чёрный текст (а для любителей яблок — серенький и синенький ) на белом фоне всегда смотрится аккуратно и профессионально, поэтому не спешите напихать в оформление кучу цветов, стилей и прочих украшений.
Все работы по оформлению ведите параллельно и независимо от написания текста. Так вы сэкономите время и быстрее получите пилотный вариант справки.
4. Контроль промежуточных версий
Условно поделите справку на несколько частей и попросите технического писателя присылать промежуточную версию справки после завершения каждой части. Все корректировки по тексту, содержанию и оформлению делайте на как можно более ранних стадиях проекта — таким образом писатель сможет учесть ваши замечания и комментарии при создании последующих текстов.
Если вы пишете текст самостоятельно, попросите сторонних людей оценить промежуточные результаты работ. Как показывает практика, это бывает очень полезно.
5. Финальная версия
Когда все топики уже написаны, сделайте небольшую паузу, чтобы отвлечься и посмотреть на результат свежим взглядом. Вдруг вы что-то упустили? А может надо что-нибудь сократить?
Прочтите получившийся хелп целиком и внесите последние правки.
6. Вычитка (пруфридинг)
Я рекомендую отдавать текст справки на вычитку профессиональному редактору. Грамотный текст и отсутствие опечаток и ошибок повышают доверие пользователей к компании и авторитет разработчика.
7. Экспорт документации
После внесения всех правок редактора и настройки оформления сделайте финальный экспорт проекта справки во все необходимые форматы. И обязательно сохраните проекты справки, иллюстрации и все исходники в файловом хранилище, чтобы при апдейте не рвать волосы на голове из-за потерянных исходников.
Инфраструктура
Для хранения проектов справки, иллюстраций и исходных данных я рекомендую использовать облачные хранилища данных с возможностью многопользовательской работы и контролем версий (dropbox, box.com), а так же онлайн-документы (googe docs, office360).
- синхронизация с локальными файлами
- система уведомлений
- комментарии к файлам
- история версий
- права доступа
- многопользовательское онлайн-редактирование, уровни доступа
- автоматическое сохранение, история изменений
- расширение функционала с помощью скриптов
- не нужно покупать пакет офисных программ
- система комментариев
Финал
После завершения работы над справкой разместите хелп в интернете, напечатайте руководство или интегрируйте контекстную справку в программу. Но это далеко не конец. Следующий этап — апдейт хелпа или перевод. Именно про эти задачи я расскажу в следующих постах.
А пока жду от вас комментариев, предложений и вопросов. Как справочную документацию пишете вы?
Alconost занимается локализацией приложений, игр и сайтов на 60 языков. Переводчики-носители языка, лингвистическое тестирование, облачная платформа с API, непрерывная локализация, менеджеры проектов 24/7, любые форматы строковых ресурсов.
Программа Dr.Explain для создания файлов справки, help (хелп) файлов и файлов помощи
Создавайте файлы справки в формате CHM и в других форматах для своего ПО, веб-сайтов, изделий
Dr.Explain поддерживает создание пользовательской документации из одного источника в различных форматах: HTML (online справка), CHM (файлы помощи для Windows-программ), MS Word, PDF.
Создавайте CHM и другие форматы: Начать с нуля очень просто
Один инструмент для всей документации!
Специальные знания не нужны! Создайте первый CHM help-файл за пару минут.
Создавайте и редактируйте разделы файла справки в удобном WYSIWYG редакторе.
Настройте оглавление, ключевые слова, меню и навигацию несколькими кликами.
Используйте Help ID для создания контекстной помощи.
Редактируйте CHM: Обновите имеющиеся файлы помощи
Отредактируйте старый файл справки!
Просто импортируйте старые файлы справки и продолжайте работать с ними в Dr.Explain. Добавьте в справку новые скриншоты, видео и эффекты.
Изменяйте дизайн и оформление файлов справки, используя предустановленные шаблоны.
Настраивайте заголовки, колонтитулы, раскладку.
Также создайте онлайн-справку или руководство пользователя по ГОСТ в формате PDF и DOC из того же проекта, без дополнительных усилий!
Конвертируйте в CHM: Превратите DOC, DOCX, RTF, HTML, HLP, XML в файл справки
Создайте файл справки из имеющихся документов!
Импортируйте HLP, TXT, XML, HTML, или MS Word документы в Dr.Explain и создайте из них единый файл.
Дополнительные утилиты не нужны.
Единое оглавление и индекс для полнотекстового поиска будут созданы автоматически.
Добавьте свои логотип, скрипты, изображения, видео, корпоративные стили и копирайты в файл справки и сделайте его частью продукта.
Приведите в соответствие с требованиями ГОСТ 34 и 19 свою пользовательскую документацию.
Примеры некоторых CHM-файлов справки, созданных программой Dr.Explain
Dr.Explain — это новый способ создвать пользовательскую документацию. Программа ускоряет этот трудоемкий процесс по сравнению с другими инструментами.
Dr.Explain умеет анализировать пользовательский интерфейс приложений и создает скриншоты (копии экранов) окон, автоматически расставляя на них пояснительные выноски для элементов интерфейса.
Процесс сильно автоматизирован. Вы сможете быстро аннотировать экраны приложений и веб-сайтов для иллюстрирования пользовательской документации на ПО.
Ставьте и работайте бесплатно —
оплатите, если понравится результат
СКАЧАТЬ И НАЧАТЬ
Видео-знакомство
Статьи о создании и использовании CHM файлов справки в Dr.Explain для приложений на разных языках программирования
Создание файла справки в формате CHM для MS Access приложения в Dr.Explain
Создание файла справки в формате CHM для приложения Delphi в Dr.Explain
Создание help-файла (справки) в формате CHM для MS Excel-приложения при помощи Dr.Explain
Создание help-файла (справки) в формате CHM для Visual Basic (VB)-приложения при помощи Dr.Explain
Создание help-файла (справки) в формате CHM для .NET (C#)-приложения при помощи Dr.Explain
Создание руководства пользователя программного обеспечения по ГОСТ
Для чего нужен CHM-файл справки
Файл справки или файл помощи в формате CHM — это набор веб-страниц, сжатых и скомпилированных в единый файл. Сейчас одним из самых популярных форматов файлов справки для приложений является именно CHM. Без файла справки ваша программа является просто программой, но не программным продуктом.
Даже если вам как разработчику понятна логика работы и способы использования вашей программы, то для сторонних пользователей это может быть не очевидно. Именно файл справки и должен решить эту проблему. Тезис о том, что никто не читает документацию — миф, выдуманный разработчиками, которым лень писать справку к своей программе.
Как создать контекстную помощь из файла справки
Файлы справки в формате CHM являются самым подходящим средством для быстрого создания контекстной помощи для вашего Windows-приложения. Практически все современные языки программирования и среды разработки содержат встроенные методы для связи компонентов вашей программы с созданным файлом справки в формате CHM. Эти методы основываются на HtmlHelp API фирмы Microsoft, которое позволяет открывать конкретные разделы или выполнять поиск по конретной фразе в созданном файле справки прямо из вашего приложения.
Для создания файла справки в программе Dr.Explain требуется только Dr.Explain
Вы можете редактировать разделы файла справки прямо в редакторе Dr.Explain, а затем просто нажать кнопку компиляции файла справки и получить готовый файл за минуту-другую.
Ставьте и работайте бесплатно —
оплатите, если понравится результат
СКАЧАТЬ И НАЧАТЬ
Видео-знакомство
Источник: www.drexplain.ru
Создаем полноценный Help для Delphi-программ. Часть 1: первое знакомство с HHW.
уважаемые посетители блога, если Вам понравилась, то, пожалуйста, помогите автору с лечением. Подробности тут.
Help…как же я ненавижу всю работу, связанную с созданием всякого рода хелпов. И ведь никуда от это работы не деться. Без полноценного, качественного help’a, контекстных справок, hint’ов и т.д. любая сколь угодно функциональная программа с «интуитивно понятным» интерфейсом может превратиться в нечто непостижимое для пользователя.
Понятно, что редко кто читает Help к медиаплееру или текстовому редактору. Но совсем другое дело, когда пишется какая-то специализированная программа, например, ГИС или, как приходилось писать мне — программы расчёта приземных концентраций загрязняющих веществ — тут хочешь-не хочешь, а на пальцах всё объяснить пользователю за пять минут не получится — большое количество переменных, задаваемых пользователем, работа с БД — все эти моменты приходится прописывать в справку. До сих пор я обходился в работе простыми html-файлами, но рано или поздно надо было переходить на использование возможностей Windows. И видимо сегодня этот день настал :).
Как Вы знаете, для хранения справочной информации Windows активно использует chm-файлы. Достаточно удобный и легкий в плане работы формат. Именно такую справку мы и будем писать сегодня.
Для компиляции и работы с chm-файлами воспользуемся тем, что предлагает нам Microsoft — программой «HTML Help Workshop» скачать которую можно, перейдя по ссылке. Там же скачайте и всю документацию по API работы со справочной системой — она нам пригодиться на будущее.
И первое, что мы сделаем — это установим «HTML Help Workshop» (HHW) и создадим новый проект, содержащий всего один файл.
Жмем в главном меню HHW File—>New и в открывшемся окне выбираем «Project» — запустится мастер создания нового проекта.
Первый шаг можно пропустить т.к. мы ничего не конвертируем. Далее нас попросят задать расположение файла проекта на диске — указываем и остальные шаги пропускаем. В конце жмем «Готово» и hhw сгенерирует нам новый пустой проект справки:
Можете установить новые свойства вашего проекта — для этого надо сделать двойной щелчок по секции «Options» или нажать одноименную кнопку в левой части окна.
Теперь создадим наш первый (и единственный) в проекте файл справки. Для этого жмем в главном меню File—>New—>HTML File. В открывшемся окне пишем название нового раздела справки, например, «Hello World!» и HHW создаст для нас «скелет» нового документа:
Так как никаких визуальных средств для разработки hhw не использует, кроме редактора в стиле «а-ля блокнот», то будем писать весь HTML-код ручками.
Для начала запишем следующее:
Содержание скрыть
Это наш первый html-файл для супер-спраки для супер-программы Hello World!
Жмем кнопку Save в верхнем тулбаре, задаем имя файла, например, index и сохраняем файл на диск.
Теперь прицепим этот файл к проекту. Для нажимаем кнопку «Add/Remove topic files», затем в открвшемся окне кнопку «Add» и добавляем наш файл index.html к проекту:
Теперь надо наш проект скомпилировать. Для этого в главном меню программы необходимо выбрать File—>Compile и в открывшемся окне указать путь к файлу проекта (по умолчанию поле ввода содержит путь к текущему файлу проекта). В результате компиляции hhw выдаст нам в главном окне лог компиляции и создаст chm-файл справки.
Если Вы делали все как написано в посте, то Вы должны были получить в результате работы три файла: *.chm, *.hhp и *.html. Теперь можете открыть получившийся chm-файл и убедиться, что наш текст из index.htm в нем присутствует:
.
Теперь нам остается научиться вызывать этот файл из своей Delphi-программы.
В Сети вы можете встретить массу статей, касающихся запуска chm-фалов из своих программ. Обчно в этих статьях Вам сначала предлагают импортировать библиотеку, обявить вызов функции HtmlHelp и уж потом работать со справкой. Но дело в том, что модуль Windows.pas в Delphi 2010 уже содержит все необходимые типы данных и функции для работы с chm.
Создайте новый проект Delphi и поместите на главную форму всего одну кнопку. Убедитесь, что в uses подключен модуль windows и в событии onClick кнопки напишите всего одну строку:
HtmlHelp(handle,’Путь_к_файлу/help.chm’,HH_DISPLAY_TOPIC,0);
Убедитесь, что файл справки запускается корректно. Теперь разберемся, что мы написали.
handle — первый параметр функции содержит всегда HWND окна вызывающего приложения.
Второй параметр — путь к файлу справки. В этом же параметре можно указать конкретный раздел справки, который необходимо открыть, название окна и т.д.
Третий параметр (HH_DISPLAY_TOPIC) — команда API. В конкретно нашем случае мы попросили открыть топик справки.
И последний параметр — ноль. Этот параметр используется, например, для команды вызова pop-up окна справки (об этом поговорим позже), в остальных случаях четвертый параметр должен быть равен нулю.
В следующий раз поговорим более подробно о структуре справочной системы и попробуем использовать другие возможности для работы со справкой, используя всё туже единственную функцию HtmlHelp.
Источник: webdelphi.ru