Создать руководство пользователя для программы

Писать руководство пользователя по шаблону. Удобно? Удобно

Команда, разрабатывающая софт для создания пользовательской документации, делится лайфхаками на тему написания идеальной пользовательской документации для тех, кто далёк от написания руководств к программе.

Для чего мы сами конструируем некоммерческие образцы документации и инструкций для пользователей

Наш проект существует и развивается уже долгое время, практически шестнадцать лет, если быть точнее. За этот срок была сформирована определенная база, где собраны самые актуальные и насущные вопросы, которые возникают перед людьми, создающими справочные элементы к своему проекту.

Ведя диалог с нашими клиентами, мы смогли выделить их потребности и понять основную «боль». Если обобщить, основная проблема заключалась в том, что ни одна программа для создания файл-справок и инструкций не могла выполнить самую нудную, энергозатратную часть проекта — само разрабатывание и оформление этой пользовательской документации

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

Отсюда вытекает еще одна загвоздка. Люди, у которых нет опыта и в принципе понимания, как начать и что туда вносить, просто не знают, как создать качественное руководство для пользователей. В таких случаях большинство следует привычному пути: загуглить определение и найти готовый шаблон.

И с какой-то стороны, это разумно. Мы достаточно часто сталкиваемся с такими запросами, пользователи просят у нас пошаговое руководство или хотя бы костяк готовой инструкции.

Так вышло, что потребности наших клиентов практически на сто процентов входят в нашу экспертную сферу. И мы приняли решение по возможности помочь всем, кто хочет (или вынужден) заниматься созданием файл-справок и инструкций к своему продукту и предоставить возможность получить образцы, которые могут послужить базой и легко быть адаптированными под конкретный запрос.

В связи с этим, мы сами создали готовые образцы и костяки шаблонных проектов в программе. Что входит в нашу базу:

• Руководство пользователя программного обеспечения.

• Руководство пользователя web-сервиса.

• Корпоративная база знаний компании.

В чем удобство создания руководства пользователя по образцу

Вы бережете своё время.

Адаптируя уже созданный образец под свой продукт, вы не тратите время на создание основы с нуля, вам не нужно тратить время, чтобы найти мастер-класс о том, как правильно это сделать. Используя готовый шаблон документации, вы значительно экономите время на создание структуры проекта с нуля и на поиск и изучение информации о том, как это делается.

Вы сосредотачиваете внимание на вашей программе, а не на создании файл-справки

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

Наглядность.

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

 Адаптация шаблонов и образцов под ваш проект.

Всё, что находится в шаблонах, можно назвать нашим советом, который был создан на основе многолетнего опыта в данной сфере и выработанной экспертностью. Абсолютно всё в этих шаблонах может быть подвержено адаптации, так как для пользовательской документации нет жестких стандартов, она должна быть выстроена персонально под ваш продукт.

О шаблонах

За 15 лет мы смогли подвергнуть аналитике более сотни разных файл-справок, инструкций и технических документаций, что дало нам возможность сделать вывод и определить шаблонные разделы, которые могут быть применены к огромному количеству программ, после чего мы интегрировали их в наши образцы. Давайте немного подробнее поговорим о структуре.

Обзор возможностей программ. Здесь идет краткое содержание сути вашего продукта. Где вы рассказываете о том, для чего нужна ваша программа. Какие боли и потребности она удовлетворяет, на что способна.

Пользовательский интерфейс. Здесь вы можете наглядно показать вашему клиенту интерфейс, ознакомить его со всеми режимами, дополнительными кнопками и.т.д. Если пользователь может персонализировать интерфейс под себя, об этом тоже лучше указать именно в этом разделе.

Типовые задачи. Здесь нужно максимально подробно познакомить пользователя со всеми основными возможностями программы и детально описать ряд задач и вопросов, которые клиент сможет решить с её помощью. В нашем образце этот блок сформирован из двух подразделов. В подразделе «Примеры использования» лучше всего рассказать пользователю, как ваш продукт будет решать его вопросы и задачи. Если обобщить, то в этом подразделе вы рассказываете про клишированные проблемы, с которыми сталкивается большинство пользователей. В подразделе «Лучшие практики» лучше разместить максимально полезную информацию о том, как упростить свою работу в программе и как пользоваться ей максимально эффективно.

Особые случаи. Здесь нужно рассказать пользователю про то, какие трудности могут возникнуть и как их решить, выделить часто задаваемые вопросы и дать на них самый доступный ответ. Подразделы: «FAQ» и «Устранение типовых проблем»

Вспомогательная и юридическая информация. Здесь вы размещаете информацию о компании, размещаете контактные данные тех.поддержки, информацию о сотрудничестве, сайт, а также лицензионные соглашения.

Названия проекта публиковать не будем, Хабр ругается.

P.S. Мы будем рады, если наши образцы помогут вам закрыть вопрос и успешно реализовать документацию в своем проекте.

Многие согласятся, что написание документации пользователя к ПО или сервису нелегкая задача.

Разработчики часто откладывают создание подобной документации в долгий ящик, поскольку считают ее трудоемкой, требующей дополнительных расходов или прямо-таки скучной.

Нужно досконально изучить программу, предсказать, с какими трудностями могут столкнуться пользователи, описать все возможности продукта, создать логичную структуру, добавить достаточно скриншотов и пояснений. И когда все будет готово – выложить документацию на сайт продукта и/или внедрить справку в ПО.

Часто подобную документацию пишут в текстовых редакторах, но это значительно усложняет и без того скучный процесс. Специализированное ПО имеет множество функций, упрощающих процесс создания руководства. Например, возможность структурировать будущую документацию, создавать разделы, делать пояснения на скриншотах, экспортировать контент в различные форматы (HTML, CHM, PDF) и многое другое.

Если вам не нравится процесс документирования продукта, над которым вы работаете, этот обзор для вас.

В нем мы расскажем, про лучшие инструменты для создания пользовательской документации на рынке, которые превратят эту тяжелую и, казалось бы, невыполнимую задачу – в легкую прогулку.

Но разве техническая поддержка не может стать заменой документации?

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

— Поддержка может подвести. Случайно или из-за некомпетентности сотрудников. Грубость техподдержки – тоже нередкое явление.

Также, техподдержку могут просто завалить вопросами, и она не будет успевать отвечать.

Подобные случаи негативно сказываются на репутации и лучше заранее застраховаться. Например – создать руководство пользователя.

Сегодня мы подобрали для вас 5 лучших программ и сервисов для создания пользовательской документации, которые, по нашему мнению, лучше всего подходят для своей роли.

1. Dr.Explain

Операционная система – Windows

Цена – от 10 000 рублей в год или 16000 рублей навсегда в рамках старшей версии (есть бесплатная версия)

Dr.Explain – одна из немногих программ, которая автоматизирует процесс создания документации пользователя. При написании документации перед писателем стоит задача наглядно показать, как все работает и где что находится. Для этого в руководства вставляют скриншоты с пояснениями к элементам интерфейса программы. В Dr.Explain есть специальный инструмент, который выделяет все важные элементы на скриншоте, например, кнопки или поля, и добавляет к ним аннотации (выноски) с пояснениями. Все что останется сделать писателю – снабдить их описаниями.

Второе, что бросается в глаза, когда изучаешь возможности программы — встроенные шаблоны документации. Всегда проще работать по образцу, смотреть на пример документации, дополнять и видоизменять под свой продукт. Именно это и предлагает Dr.Explain. В программе существует три шаблона документации: руководство пользователя для ПО, руководство пользователя для web-сервиса и шаблон корпоративной базы знаний.

Как бы хорошо программа не помогала писать документацию, конечная цель – это публикация контента на сайте продукта и интеграция его в продукт, чтобы пользователи могли прочитать ваше руководство. Dr.Explain позволяет экспортировать ваш проект в популярные форматы: HTML – для сайта, CHM – для встроенной в ПО справки и PDF.

Dr.Explain позволяет работать в команде через облачный сервис или локальный сервер. В программе можно задавать разделам «степень готовности». Так вы сможете контролировать процесс написания справки.

В программе имеется удобный и продуманный WYSIWYG (What You See Is What You Get, «что видишь, то и получишь») редактор, возможность настраивать стиль вашей документации, возможность настроить контекстно-зависимую справку и что немаловажно – в ней есть русский интерфейс, так как Dr.Explain – проект отечественной команды разработчиков и продукт включен в реестр отечественного ПО.

+ Большой перечень возможностей, позволяющих создать качественное и полное руководство пользователя (аннотирование скриншотов, шаблоны документации и т.д.)

+ Русский интерфейс

+ Простая оплата для российских пользователей

Минусы:

— Отсутствие веб-интерфейса

— Отсутствие версии для Mac и Linux

— Нет вывода в ePub, markdown и другие специфические форматы

2. HelpnDoc

Операционная система – Windows

Цена – от $99 в год (есть бесплатная версия)

Главный плюс HelpnDoc – возможность экспорта в невообразимое множество форматов, тем самым возможность создания мультиформатной документации.

Создаёте документацию для мобильного приложения? Вашим пользователям нужно читать документацию с электронной книги? Нужно создать документацию к продукту на Linux, Ubutu, UNIX? Эта программа поможет.

Мощная система медиабиблиотеки. Все медиа-элементы, такие как изображения, видео, документы, фрагменты HTML-кода, управляются библиотекой: эти медиа-элементы можно использовать повторно много раз.

Нужно изменить одну картинку, а она размещена в документации десятки раз? Просто обновите элемент библиотеки, и он будет распространен на все темы, использующие его.

Благодаря редактору сценариев можно легко автоматизировать повторяющиеся задачи и сфокусировать своё внимание на сложных. Вам нужно изменить порядок тем? Заменить все элементы библиотеки? Запустите редактор сценариев, введите несколько инструкций, нажмите «Выполнить», после чего часть рутинной работы будет выполнена автоматически.

HelpnDoc анализирует написанную документацию и может показать вам неработающие ссылки, ссылки с ошибками, отсутствующие или дублирующие элементы мультимедиа. Все подобные ошибки можно увидеть в одном месте (анализаторе) и сразу же приступить к их устранению.

Плюсы:

+ Возможность создания мультиформатной документации.

+ «Сценарии» значительно упрощают и ускоряют процесс написания руководства

+ Умный анализ и проверка вашего проекта.

Минусы:

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

— сравнительно сложный пользовательский интерфейс.

— сложность с оплатой лицензий для российских пользователей.

3. ClickHelp

Операционная система – любая.

Цена – от $50 в месяц.

ClickHelp в отличие от двух предыдущих – не программа, это web-сервис для создания документации.

Сервис полезен для продуктов, которые хотят выйти на международный рынок. В ClickHelp существует возможность перевода вашего руководства на любой язык, при помощи Google, конечно. Что немаловажно, изменяя исходный текст, изменения будут отображаться во всех переведенных вариантах на этих же языках.

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

Специально для этого в ClickHelp есть ряд функций, чтобы клиенты всегда могли найти ответ на свой вопрос:

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

— Система индексов. Если вы думаете, что пользователю все равно будет трудно найти какую-то информацию в вашей документации – система индексов или таксономий в ClickHelp решит эту проблему. Данная функция предназначена для того, чтобы сделать темы доступными для поиска по терминам, которые не находятся непосредственно в их содержании. Например, если в документации есть тема о SSL-шифровании, вы можете присвоить ей индексное ключевое слово «безопасность», и даже если в теме нет ни единого упоминания «безопасности» или каких-либо производных, она все равно будет доступны для поиска по этому термину.

В ClickHelp можно работать в команде. Сервис позволяет следить за процессом разработки, оставлять комментарии, от которых уведомления будут приходить на почту, раздавать роли.

Плюсы:

+ Возможность работы в команде через веб-интерфейс и отслеживание результатов.

+ Поиск по документации.

+ Автоматический перевод документации на любые языки.

Минусы:

— Достаточно сложный в освоении продукт и интерфейс только английский, что усложнит задачу понимания сервиса и его функций.

— Высокая стоимость лицензии.

— Нет возможности работать в offline-режиме.

4. HelpSmith

Операционная система – Windows

Цена – от $199.

Одной из основных возможностей HelpSmith является создание нескольких форматов справки из единого источника. Таким образом, имея один исходный текст, вы можете экспортировать его в HTML для создания веб-справки, в PDF, MS Word, а также в формат ePub для электронных книг.

Программа имеет встроенный инструмент по работе с изображениями, чем-то напоминающий Dr.Explain. В нем вы можете редактировать изображения и добавлять к ним аннотации. Кроме того, всё медиа, которое вы используете в проекте, хранится в едином репозитории, что упрощает процесс обновления и сохранения изображений в документации.

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

Следует отметить, что файл справки или систему веб-справки можно легко интегрировать в ваше приложение или веб-сайт, поэтому вы можете предоставлять контекстно-зависимую справку, экспортируя список тем в файл заголовка, совместимый с вашей IDE, такой как C #, VB .NET, Delphi, C++, MS Office VBA.

Также, из необычных дополнительных функций HelpSmith является — «Подсветка синтаксиса» — для создания документации API, файлов справки с примерами кода и любых других видов документации, содержащей программный код, написанный на различных языках программирования.

Плюсы:

+ большой перечень возможностей, позволяющих создать качественное и полное руководство пользователя

+ простота и удобства использования.

Минусы:

— Отсутствие простого механизма многопользовательской работы

— Интерфейс и материалы на английском языке

— Отсутствие Mac и веб-версии

5. MarkdownPad

Операционная система – Windows

Цена – бесплатно. Есть платная версия – $15.

MarkdownPad — известный редактор Markdown для Windows. Он прост и так же удобен в использовании, как Microsoft Word, и поставляется с редактором WYSIWYG, поэтому вам даже не нужно знать Markdown.

MarkdownPad отлично подходит, если вам нужно быстро выложить документацию на сайт, создать веб-сайт и все, что связано с HTML. Вы можете в любой момент посмотреть, как будет выглядеть ваша документация, используя предварительный просмотр.

Все настраивается под себя. Вы можете воспользоваться широкими возможностями настройки, такими как макеты, шрифты и размеры. Вы также можете включить свои собственные таблицы стилей CSS. Он поставляется со встроенным в платформу редактором CSS, поэтому вы можете стилизовать текст по своему вкусу.

Плюсы:

+ Очень удобная и в целом простая программа, что даже не получилось написать про неё больше 3 абзацев

+ Стоимость.

Минусы:

— Малый функционал, по сравнению с большинством подобных инструментов.

Заключение

Пользовательская документация – незаменимый инструмент, позволяющий укреплять лояльность пользователей, прикрывать техподдержку, повышать SEO-факторы продукта. Кроме того, наличие технической документации — один из основных критериев допуска в Реестр отечественного ПО Минцифра России.

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

Всем доброго времени суток, кто решил прочитать статью, посвященную документации. Здесь вы найдёте как общие, так и довольно специфические советы по созданию руководства пользователя. Надеюсь, они будут вам полезны.

Приятного чтения.

Если перед вами стоит вопрос – нужно ли вашему продукту пользовательское руководство, то отвечу сразу – да, нужно. Почему? На это есть две причины:

1. Качественная документация повышает лояльность клиента и ценность продукта в целом.

Как это не странно, но люди до сих пор читают пользовательскую документацию. Конечно, не просто так, а когда сталкиваются с проблемой. И если с руководством все хорошо, то пользователь быстро найдет ответ на свой вопрос – это будет ещё один балл в копилку вашего проекта!

2. Руководство пользователя экономит время и силы техподдержки.

Данный факт напрямую зависит от первого. Если документация качественная, то пользователи будут редко обращаться в техподдержку, и ваша команда будет работать с действительно нестандартными ситуациями. Ну а если руководство «так себе», то поддержка будет завалена однотипными вопросами. Из-за этого пользователям придется дольше ждать ответа, поддержке больше работать, а это в свою очередь будет злить как пользователя, так и команду.

А теперь к советам!

Общие советы по созданию руководства пользователя

Прежде чем начинать писать руководство пользователя нужно ответить на несколько вопросов. — Для кого вы пишите? Кто будет пользоваться файлом справки? (ваша целевая аудитория)

— Где скорее всего пользователи будут прибегать к документации? (дома, на работе, в машине)

— Насколько объективно сложен для понимания продукт и как часто пользователь будет обращаться к документации?

И так, вы ответили на эти вопросы и теперь можете сделать вывод какого размера документация вам нужна, какой стиль изложения в ней использовать, и как часто пользователь будет читать документ.

(Для изложения лучше всего выбрать нейтрально-формальный стиль)

Структура руководства пользователя

У любого качественной документации продуманная и логичная структура. Представьте, что вы сами работаете в программе и сталкиваетесь с проблемой. Открываете файл справки – а там просто сплошной текст. Такая документация вам не поможет.

Создайте оглавление, которое будет началом вашего руководства. Оно поможет вам в дальнейшем написании документации, а также поможет пользователю ориентироваться в тексте.

В первом разделе расскажите общую информацию о продукте. Для чего создан проект и какие задачи он решает.

Во второй «главе» укажите основные элементы интерфейса. Клиент вряд ли сможет достичь своей цели в программе, если не будет знать для чего служат различные детали интерфейса. Объясните предназначение всех окон, кнопок и так далее.

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

В любом руководстве желательны разделы «Частые вопросы» и «Устранение типовых проблем». Расскажите о проблемах, с которыми часто сталкиваются клиенты и о путях их решения.

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

И последний «обязательный» раздел, которой точно должен быть в любой документации – «контактная информация». Данный раздел даст пользователю возможность связаться с разработчиком. Если руководство вдруг не закрывает потребность читателя, то он может обратиться в поддержку. Кроме того, клиент может дать совет, поделиться опытом или предложить выгодное вам сотрудничество.

Профессиональный совет: если вы хотите максимально облегчить ношу клиента при чтении документации создайте контекстно-зависимую справку. Что это такое?

Представьте, что вы работаете в программе для создания пользовательской документации. Открываете меню основных настроек и видите раздел «аннотирование экрана» Заходите в него, там показаны разные стили аннотации, тени, фон и так далее. Но что такое аннотация? Допустим вы не знаете — нажимаете кнопку F1 и перед вами открывается руководство именно на той странице, где рассказано об «аннотировании экрана»

Как ее сделать? Смотрите ниже.

Контент

И так, мы создали «каркас» нашей документации, но чтобы руководство стало полезным нужно наполнить её компетентной информацией.

Конкретного совета дать невозможно, так как все продукты разные. Поэтому расскажу про общие положения, которые делают документацию лучше.

1. Понятность.

Помните, что руководство будут читать люди, которые не сильно знакомы с вашим продуктом. Пишите простым языком, избегайте профессиональных терминов. Руководство пользователя должно быть написано на языке этого самого пользователя, а не на языке писателя.

2. Наглядность.

Добавляйте в руководство побольше графики и скриншотов с аннотациями. Читателю будет проще и приятнее решать проблему, если будет наглядно показано как это делать.

3. Видео.

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

Но как добавить в документацию видео? Смотрите ниже.

Больше советов!

Когда документация будет готова, чтобы она стала «полноценной» её нужно опубликовать. Иначе какой от неё толк, если клиент не может её прочитать. У «юзера» всегда должен быть доступ к документации, и не важно где он. Такую потребность легко закрывают три формата: HTML, PDF и CHM.

Создайте файл справки и загрузите его прямо в вашу программу в формате CHM. Таким образом, у пользователя будет возможность открыть документ, не выходя из программы. Не забудьте добавить элемент вызывающий руководство в меню программы.

Выложите руководство на сайт в формате HTML, чтобы клиент мог обратиться к документации, даже не работая с программой. Кроме того, документация, выложенная на сайт, повышает SEO факторы сайта.

И напоследок, переведите пользовательскую документацию в формат PDF, чтобы клиенты могли скачать и распечатать руководство.

Но помните, что после публикации документации, придется иногда её обновлять.

Инструменты

Для того, чтобы написать, а затем опубликовать документацию одного Wordа не хватит, но и пользоваться большим количеством программ тоже не хочется.

Ну и пользуясь случаем, я хочу рассказать про проект, в котором я работаю уже много лет и который закрывает все потребности писателей пользовательской документации.

Dr.Explain – программа для создания руководств пользователя для ПО, web-сервисов и баз знаний.

Благодаря «доктору» вы сможете опубликовать и обновлять документацию в востребованных форматах (CHM; HTML; PDF; DOC), не выходя из программы.

В программе есть шаблоны документации, ведь по образцу работать проще.

Импортируйте в программу заранее написанные фрагменты документации.

Вы сможете создать контекстно-зависимую документацию, настроить визуальный стиль руководства, добавить в него видео и многое другое!

Какой можно сделать вывод

Если вы хотите создать по-настоящему хорошую документацию – придется потрудиться, потому что это займет много времени и усилий всей команды. Но игра стоит свеч, так как после этого вы получите лояльных и довольных клиентов.

Руководство пользователя должно стать персональным гидом по продукту для клиента. Если пользователь останется недовольным после работы с документацией, то это может повлиять на решение отказаться от продукта.

Работая с Dr.Explain, можно быстро написать пользовательскую документацию, которая будет помогать клиентам разбираться в продукте, а вам позволит сосредоточить свои силы на более важных задачах — разработке и продвижении программного продукта.

Спасибо за внимание!

Со всеми возможностями Dr.Explain можно ознакомиться здесь:

Сравнительный анализ структур руководств пользователя программы по ЕСПД и IEEE Std 1063-2001 с учетом рекомендаций «манифеста Кагарлицкого». Показано, что обобщенная структура руководства пользователя, собранная согласно требованиям «устаревших» ГОСТов 19-й системы, существенно превосходит структуру руководства, рекомендуемую суперсовременным IEEE Std 1063-2001. Редакция от 23.01.2022.

Создан 11.02.2005 11:14:22

Когда умирает надежда, приходит отчаяние.

Мудрая латинская поговорка

Как писать руководство пользователя программы? Создать древовидную иерархическую структуру разделов руководства пользователя и заполнить ее разделы содержимым. И вся любовь.

Где взять структуру разделов руководства пользователя? С руководствами на изделия (руководство по эксплуатации по ГОСТ 2.601-95) и на автоматизированные системы (руководство пользователя по РД 50-34.698-90) все более или менее ясно. А вот сам документ «Руководство пользователя» программы в ГОСТах 19-й системы отсутствует как класс.

Каким содержимым наполнять разделы руководства пользователя? Как быть? Главное — не отчаиваться.

Цели и задачи статьи

Цель, как всегда, — попытаться облегчить жизнь разработчику руководства пользователя программы.

Задачи:

• проанализировать существующие стандарты и рекомендации по разработке эксплуатационной программной документации, выявить достоинства и недостатки каждого документа по отдельности;
• вывести некую обобщенную структуру руководства пользователя по ГОСТам 19-й системы из имеющегося набора эксплуатационных программных документов;
• сравнить ее со структурой, рекомендованной IEEE Std 1063-2001;
• а все прочие задачи перекочевали во 2-ю часть статьи…

Примечание от 10.07.2014 г. — В феврале 2005 года был проведен, пожалуй, даже не сравнительный анализ, а скорее сравнительные испытания, показавшие неоспоримое превосходство ГОСТов 19-й системы стандартов над буржуйскими и практически полную несостоятельность последних.

Вопросы, на которые должно дать ответы руководство пользователя

Подарите ребенку незнакомую ему электронную игрушку. Перечень вопросов будет примерно таким (если сразу же не разломает):

• а что это;
• а что им можно делать;
• а что им нельзя делать (у особо одаренных);
• а что надо, чтобы оно работало;
• а что там у него внутри (у детей, склонных к глубокому анализу);
• а как его настроить, чтобы работало так, как я хочу;
• а как его проверить, работает оно или не работает;
• а что и где надо нажимать;
• а что оно еще может делать;
• а что оно говорит, если что-то не так нажимаешь?

Последовательность вопросов может оказаться самой разнообразной. И документ под названием «Руководство пользователя» должен дать ответы на все поставленные вопросы. Все просто. Не так страшен черт, как его малюют.

Руководство пользователя: четыре источника и четыре составных части

Располагаем документами:

• «метагайдом» Кагарлицкого;
• суперсовременным IEEE Std 1063-2001, «IEEE Standard for Software User Documentation»;
• классическими отечественными ГОСТами 19-й системы, включающим в себя перечисленные ниже документы «описательного» характера:
  • ГОСТ 19.402-78 ЕСПД. Описание программы;
  • ГОСТ 19.502-78 ЕСПД. Описание применения. Требования к содержанию и оформлению;
  • ГОСТ 19.503-79 ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению;
  • ГОСТ 19.504-79 ЕСПД. Руководство программиста. Требования к содержанию и оформлению;
  • ГОСТ 19.505-79 ЕСПД. Руководство оператора. Требования к содержанию и оформлению.

Крайняя четверка из перечня — эксплуатационные программные документы.

Возможно, существуют и иные документы, но автору, основательно порывшемуся в рунетовской свалке, ничего более подходящего заполучить пока не удалось. Яндекс обнаружил в своих недрах еще одну страничку с названием «Как сделать хорошее руководство пользователя», автор которой именует себя на американЬский манер (типа John P. Morgan). Двухстраничное «наставление» с радостными возгласами было немедленно отправлено в корзину.

Манифест Кагарлицкого

Метагайд Кагарлицкого показался многообещающим. Только автор настоящей статьи не уразумел, что есть «метагайд», поэтому позволил себе наглось обозвать метагайд «манифестом». И не погрешил против истины (но это открылось позже — ниже).

(цитаты из манифеста Кагарлицкого)

Мы стремились свести в единую систему всю совокупность типовых требований, которые должны, с нашей точки зрения, предъявляться к технической документации: руководствам, справочникам и т.д. При этом мы основывались на стандартах(!!!) ГОСТ, стандартах компании Microsoft, опыте наших сотрудников и других разработчиков технической документации.

Начало обнадеживающее.

В состав технической документации входят две стержневые части, которые мы будем называть соответственно руководством пользователя и справочником пользователя, или коротко: руководством и справочником (по аналогии с английскими словосочетаниями User’s Guide и User’s Reference). Они могут быть оформлены в виде отдельных документов (для крупных программных продуктов), а могут, напротив, существовать в интегрированном виде. Между ними даже может не быть четкой границы: единый текст способен совмещать в себе черты руководства и черты справочника.

Что-то не так. Автору статьи всегда «казалось», что термин техническая документация трактуется более широко, значительно шире, чем эксплуатационная (программная) документация.

Руководство и справочник — это не столько части документации, сколько понятия, которые воплощают собой два подхода к описанию программного продукта.

По-понятиям так по-понятиям, вот только пацаны начинают нервничать. Руководство не есть понятие, а есть вид документа.

Наша задача не столько в том, чтобы рассказать, как выглядит документация, сколько в том, чтобы дать конкретные рекомендации по ее разработке. Всем известно, какие проблемы возникают в процессе написания связного текста большого объема — как приступить к работе, с чего начать, как расположить материал. Этот подход побуждает видеть в провозглашаемых нами нормах не хаотический их перечень, а иерархическую систему…

На небосклоне засияла звезда по имени Надежда — сейчас уважаемый г-н Кагарлицкий выдаст нам, лишенцам, всеобъемлющую иерархическую структуру руководства пользователя всех времен и народов. Ну же?!

Прежде чем приступить к разработке документации как таковой, необходимо наметить и спланировать общую логику изложения. Может показаться, что жанр технической документации крайне прост: ведь его задачей является «всего лишь» сообщение пользователю некоторых сведений о продукте. Однако если Вы будете исходить из этого в своей работе, Вы будете создавать образцы документации, вовсе непригодные или едва пригодные для практического использования, — даже если все необходимые сведения будут там содержаться. Ваша задача состоит в том, чтобы провести пользователя через перевал, то есть найти в горной цепи место, которое хотя бы и с трудом, но все-таки проходимо для Вашего «подопечного».

Жаль… А так все хорошо начиналось. Со «стандартов ГОСТ» — «стандартов ГОсударственных СТандартов» — простим г-на Кагарлицкого за тавтологию. Только вот решения первой задачи, поставленной автором настоящей статьи, в семидесятидвухстраничном манифесте (Arial’ом 12pt) нет. Уважаемый автор манифеста лишь поставил нам задачу. Что ж, нет пророка в своем отечестве. Может, есть пророк в отечестве буржуйском?

Руководство пользователя по IEEE Std 1063-2001 «IEEE Standard for Software User Documentation»

Забугорный «пророческий» документ IEEE Std 1063-2001 (IEEE в простонародье — «ай-яй-яй») в подразделе 1.2 (Puprose) содержит такую строчку:

This revision provides requirements for the structure, information content, and format of both printed and electronic documentation.

В авторском понимании назначение (намерение, цель, замысел, стремление) документа IEEE Std 1063-2001 состоит в «обеспечении требований к структуре, информационному наполнению, форматированию (оформлению) как электронной, так и печатной пользовательской документации по программным средствам». Что ж, подходяще. Какую же структуру руководства пользователя предлагает IEEE Std 1063-2001?

Структура руководства пользователя по IEEE Std 1063-2001

Опциональная типовая структура руководства пользователя содержится в таблице из раздела Structure of software user documentation документа IEEE Std 1063-2001:

For purposes of this standard, the following non-mandatory nomenclature is used for the structural parts of software user documentation. A printed document is structured into logical units called chapters, subdivided into topics, which may be subdivided into subtopics, and printed on physical units called pages.

Здорово. IEEE Std 1063-2001 предлагает «все взять и поделить» — разбить разделы руководства на главы, топики, субтопики и т.д. И наступит всем счастье.

Практический интерес (в рамках задач статьи) представляют выделенные разделы. Посмотрим, как дробить разделы руководства пользователя на более мелкие структурные единицы и каким содержимым предполагается заполнять указанные структурные единицы.

Introduction

Какие сведения должны быть изложены в разделе Introduction согласно IEEE Std 1063-2001? А вот какие

The introduction shall describe the intended audience, scope, and purpose for the document and include a brief overview of the software purpose, functions, and operating environment.

Что ж, замечательно. Структура подразделов Introduction начинает как-то вырисовываться.

Information for use of the documentation

The documentation shall include information on how it is to be used (for example, help on help), and an explanation of the notation (a description of formats and conventions-see 5.8). At least one document in a document set shall identify all documents in the set by title and intended use, including recommendations on which members of the audience should consult which sections of the documentation. In document sets comprising many volumes or products, this information may be provided in a separate «road map» or guide to the document set. Documentation may include identification and discussion of notable changes from the previous version of the document set and the software.

Весьма полезный раздел (в контексте разработки руководства пользователя). Руководство по руководству.

Concept of operations

Documentation shall explain the conceptual background for use of the software, using such methods as a visual or verbal overview of the process or workflow; or the theory, rationale, algorithms, or general concept of operation. Explanations of the concept of operation should be adapted to the expected familiarity of the users with any specialized terminology for user tasks and software functions. Documentation shall relate each documented function to the overall process or tasks. Conceptual information may be presented in one section or immediately preceding each applicable procedure.

Концептуальная информация безусловно важна.

Procedures

Task-oriented instructional mode documentation shall include instructions for routine activities that are applied to several functions:

— Software installation and de-installation, if performed by the user

— Orientation to use of the features of the graphical user interface (see 5.6)

— Access, or log-on and sign-off the software

— Navigation through the software to access and to exit from functions

— Data operations (enter, save, read, print, update, and delete)

— Methods of canceling, interrupting, and restarting operations

These common procedures should be presented once to avoid redundancy when they are used in more complex functions.

И пошла конктерика. Молодцы, буржуи!

Information on software commands

Documentation shall explain the formats and procedures for user-entered software commands, including required parameters, optional parameters, default options, order of commands, and syntax. Documentation may be provided on the development and maintenance of macros and scripts. Reference mode documentation shall contain a reference listing of all reserved words or commands. Examples should illustrate the use of commands. Documentation shall explain how to interrupt and undo operation during execution of a command and how to restart it, if possible. Documentation shall describe how to recognize that the command has successfully executed or abnormally terminated.

Error messages and problem resolution

Documentation should address all known problems in using the software in sufficient detail such that the users can either recover from the problems themselves or clearly report the problem to technical support personnel. Reference mode documentation shall include each error message with an identification of the problem, probable cause, and corrective actions that the user should take. A quick reference card may address error messages by referring the user to more detailed reference documentation. The documentation on resolving problems shall also include contact information for reporting problems with software or its documentation and suggesting improvements.

Выводы по IEEE Std 1063-2001

Но счастье оказалось неполным… Структура разделов первого уровня руководства показана в таблице явно. А дальше — «милый мой, хороший, догадайся сам» («догадайся, мол, сама»). IEEE Std 1063-2001, конечно, «provides requirements for the structure», но не предлагает явной структуры руководства пользователя до рекомендованного ГОСТ 2.105 четвертого уровня вложенности.

Рекомендации типа «Documentation shall explain…», «Examples should illustrate…», «Documentation shall describe…» и им подобные, безусловно, проверены временем. В руководстве пользователя надо и объяснять, и иллюстрировать, и описывать — без всякого сомнения. Но все это и козе понятно, и в ГОСТах 19-й системы прописано.

Итак, вряд ли целесообразно разрабатывать руководства пользователя, основываясь исключительно на рекомендациях IEEE Std 1063-2001. Причины, как минимум, две:

• отсутствие в IEEE Std 1063-2001 четко регламентированной структуры руководства пользователя;
• «поверхностность» IEEE Std 1063-2001, отсутствие «широты охвата» и «глубины проработки».

Отсутствие четко регламентированной структуры руководства пользователя даст возможность заказчику ТРЕТИРОВАТЬ разработчика, см. хотя бы Страшная правда о техническом задании. Бедняга-разработчик будет вынужден, по указке заказчика, изо дня в день менять местами разделы руководства пользователя (гарантированный минимум, полученный опытным путем).

Отсутствие четко регламентированной структуры оборачивается хаосом, как только уровень вложения заголовков снижается до второго-третьего. Пользователь просто зашвырнет такое руководство куда подальше и назовет его автора кретином.

По мнению автора, рекомендации IEEE Std 1063-2001, разработанного при участии сотни забугорных спецов, весьма и весьма поверхностны. Не сможет разработчик, работая по IEEE Std 1063-2001, охватить максимум «характеристик», свойственных программе. В IEEE Std 1063-2001 многие из них попросту не прописаны. Отсутствуют «широта охвата» и «глубина проработки», свойственные отечественным документам.

В крайнем разделе настоящей статьи приведена таблица соответствия ГОСТ 19 и IEEE Std 1063-2001, которую автор статьи начал было составлять, затем бросил и проверять не стал. А выводы пусть каждый сделает сам для себя. И, возможно, в чем-то поправит автора.

Пользовательские документы по ГОСТ 19 (ЕСПД)

В отличие от суперсовременного буржуйского IEEE Std 1063-2001, древние, многими ругаемые отечественные стандарты 19-й системы (Единая система программной документации — ЕСПД) содержат не пространные рассуждения о том, что и как должно разъяснять, иллюстрировать и описывать руководство пользователя, а конкретные требования к структуре и содержанию пользовательских (эксплуатационных) документов.

Перечень ГОСТов 19 «описательного» характера, на основе которых можно, не мудрствуя лукаво, сформировать четкую структуру разделов каждого из «описательных» документов, приведен в разделе Источники. Основной прием — детализация — подробно описан в статье «Как писать техническое задание?!». Далее — сформированные «детализацией» структуры разделов документов согласно ГОСТам из перечня.

Структура разделов описания программы по ГОСТ 19.402-78

Структура разделов описания применения по ГОСТ 19.502-78

Структура разделов руководства системного программиста по ГОСТ 19.503-79

Структура разделов руководства программиста по ГОСТ 19.504-79

Структура разделов руководства оператора по ГОСТ 19.505-79

Выводы по ГОСТам 19.ххх

Ни ГОСТ 19.505-79, ни ГОСТ 19.504-79, ни ГОСТ 19.503-79, взятые по одельности, не могут похвастаться достаточной полнотой структуры.

Зато структуры «описательных» документов ГОСТ 19 обладают как полностью идентичными (по тексту названий), так и схожими по тексту названий разделами и подразделами. К идентичным разделам относятся, к примеру, разделы «Аннотация», имеющие место во всех документах согласно ГОСТ 19.105-78. К схожим (фактически — идентичным) можно отнести подразделы «Назначение программы» и «Сведения о назначении программы».

А почему не попытаться объединить все «описательные» документы? Объединить идентичные и схожие разделы документов, выделить специфические разделы? Быть может, удастся избавиться от неполноты ГОСТ 19.505-79, ГОСТ 19.504-79 и ГОСТ 19.503-79 и получить обобщенную структуру «описательного» документа и обозвать сам документ руководством пользователя программы?

ГОСТы 19.ххх допускают «вводить дополнительные разделы или объединять отдельные разделы», а также «вводить новые». Согласно ГОСТ 19.101-77 «Допускается объединять отдельные виды эксплуатационных документов (за исключением ведомости эксплуатационных документов и формуляра). Необходимость объединения этих документов указывается в техническом задании. Объединенному документу присваивают наименование и обозначение одного из объединяемых документов. В объединенных документах должны быть приведены сведения, которые необходимо включать в каждый объединяемый документ [из 2.6 ГОСТ 19.101-77]»

Сказано — сделано. Только мы нарушим ГОСТы и создадим объединенный документ под названием «Руководство пользователя».

Обобщенная структура руководства пользователя по ГОСТам 19-й системы

Путем слияния структур «описательных» документов ГОСТов 19-й системы в единую структуру, удаления «лишних» одноименных разделов, слияния схожих разделов сформирована общая структура руководства пользователя программы. В табличке сведены и «*» отмечены разделы, присутствующие в каждом отдельном документе.

Выводы по обобщенной структуре руководства пользователя по ГОСТ 19.ххх

Обобщенная структура руководства пользователя по ГОСТ 19.ххх явно не страдает, как IEEE Std 1063-2001, отсутствием широты охвата. Избыток, как известно, рождает качество. Перечислено все, чем может характеризоваться программа. Отдельные подразделы могут показаться даже излишними, к примеру, подраздел «Языки программирования, на которых написана программа».

Казалось бы, какое дело пользователю, на каком языке был написан исходный текст программы? С другой стороны, может «…это кому-нибудь нужно? Значит — это необходимо…». Ведь хочется при покупке буржуйского телевизора заполучить и принципиальную схему на него. Самсунги и соньки тоже выходят из строя. А вдруг неисправность пустяковая и устранить ее представляется возможным в домашних условиях, без поездки в сервисный центр?

В то же время, при всей широте охвата, в явном виде отсутствуют:

• Software installation and de-installation, if performed by the user;
• Orientation to use of the features of the graphical user interface;
• Access, or log-on and sign-off the software;
• Navigation through the software to access and to exit from functions и многое другое.

Автору удалось разбросать кое-что в разделе Таблица соответствия ГОСТ 19.ххх и IEEE Std 1063-2001, но времени «наморщить ум» всегда не хватает, руководство пользователя, как всегда, должно было быть готово еще на прошлой неделе.

Показать связи разделов обобщенного руководства пользователя с разделами ГОСТ 19.201-78 ЕСПД. Техническое задание, требования к содержанию и оформлению автор поленился, поскольку указанные связи очевидны.

Выводы по источникам

Итак, если первые три задачи в целом решены, крайняя задача осталась нерешенной.

Автор манифеста более склонен к рекомендациям по подбору слов* и построению предложений, IEEE Std 1063-2001, в лучшем случае, приводит требования к структуре руководства пользователя, но не дает особой конкретики, в ГОСТ 19.ххх не прописаны процедуры заполнения содержимым разделов руководства. Может, организовать эдакую смесь французского с нижегородским? Использовать все четыре источника в качестве четырех составных частей?

* Нынче в моде буржуйское понятие — т.н. контролируемый язык. Среди представителей «просвещенной русской интеллигенции» наибольшей популярностью пользуется отечественный аналог в глагольной форме повелительного наклонения — фильтруй базар!

Смесь французского с нижегородским

Почему бы нет? Взять лучшее из ГОСТов 19-й системы, — обобщенную структуру руководства пользователя, добавить к ней немногочисленные толковые рекомендации из IEEE Std 1063-2001 и разбавить неисчерпаемой стилистической культурой и ресурсами языка из манифеста Кагарлицкого? Придать смеси стройный строгий вид, сформировать очередной учебно-тренировочный документ с подробными комментариями? А что делать, если ни один из перечисленных выше источников и составных частей в отдельности не способны дать ответы на все поставленные вопросы?

Таблица соответствия ГОСТ 19 и IEEE Std 1063-2001

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

Что нужно для создания справочного файла? Большинство используют для этого кнопку PrntScr и текстовый редактор. Но на самом деле можно отказаться и от того, и от другого. Есть программы и веб-сервисы, о существовании которых многие разработчики (и даже составители технической документации) просто не догадываются. Специализированные решения для создания мануалов, руководств пользователя и прочих подобных документов, как правило, объединяют текстовый редактор с минимальным набором функций, приложение для создания скриншотов, а также средства для экспорта в популярные форматы документов. Более того, некоторые из таких программ делают большую часть работы за пользователя, самостоятельно расставляя снимки экрана в нужной последовательности и даже добавляя описания. Разберем пять наиболее удачных — на наш взгляд.

⇡#Clarify 2.0.5 – быстрые мануалы без дополнительного софта

• Разработчик:Blue Mango Learning Systems.
• Операционная система: Windows/Mac.
• Распространение: shareware, $30.
• Русский интерфейс: нет.

Если говорить в самом широком смысле, Clarify – это упрощенный текстовый редактор, в который добавлены средства для быстрого создания скриншотов. Однако за этой простой фразой скрываются многие часы времени, которые могут быть сэкономлены составителями технической документации. Благодаря Clarify не нужно непрестанно переключаться между двумя приложениями и тратить время на вставку скриншотов – все собрано в одном месте.

Окно программы разделено на две части: слева идет работа с заголовками, а справа – с содержимым мануала. Каждый заголовок называется тут «шагом». Как только автор создает новый заголовок, программа тут же подсказывает, что для него нужно создать скриншот и добавить сопроводительный текст. Каждый новый заголовок автоматически нумеруется, также можно легко создавать подзаголовки, тоже пронумерованные. Впрочем, если в вашем документе номера разделов не нужны, эту функцию можно просто отключить. При помощи горячих клавиш заголовки можно быстро перемещать между разделами.

Чтобы добавить скриншот в любое место документации, достаточно выделить нужный заголовок и нажать на кнопку захвата экрана. Если скриншоты были созданы ранее, можно добавить их в документ, указав путь к ним на диске. Снимок экрана можно сделать как моментально, так и с небольшой задержкой (до пяти секунд), что может быть удобно, если нужно сделать скриншот выпадающего меню или другого элемента интерфейса, который постоянно не отображается на экране. Нажимая клавишу «Пробел», можно переключаться между захватом всего экрана или же текущего окна. Кроме этого, предусмотрены горячие клавиши для включения/выключения отображения курсора и для захвата области того же размера, что и предыдущий скриншот. Последняя функция очень удобна, если нужно делать десятки однотипных снимков экрана, так как при этом экономится время на выделение требуемой области.

Полученный скриншот сразу же вставляется в тот пункт документации, который был выделен. Что интересно: на панели навигации пункты, для которых уже добавлены снимки экрана, визуально помечены. Благодаря этому можно сходу определить, над какими разделами нужно еще поработать.

То, в каком формате будет сохранен скриншот, определяется в настройках приложения. Программа может автоматически генерировать теги ALT для картинок, масштабировать их при вставке в документ до нужного размера (исходная копия при этом тоже сохраняется), добавлять рамку, скруглять края.

В Clarify есть базовые инструменты для работы с изображениями и текстом. Так, картинки можно поворачивать, обрезать, добавлять на них текстовые надписи или комментарии, стрелки, прямоугольники и другие графические объекты, которые могут пригодиться для визуального выделения областей на скриншоте.

При работе с текстом можно использовать нумерованные и маркированные списки, вставку кода, гиперссылок, отступы. Для некоторых языков работает проверка грамматики при вводе, есть поиск и замена данных в документе.

Над проектами Clarify можно работать совместно с другими пользователями. Для этого нужно создать учетную запись на сайте Clarify-it.com. Кроме этого, программа поддерживает сервисы Dropbox и Evernote, дает возможность экспортировать проекты в PDF, Word, HTML и на сайты WordPress. При желании можно также просто скопировать весь текст документа (или же текст с картинками) в буфер обмена.

При экспорте можно выбирать тему оформления, добавлять колонтитулы, управлять разными параметрами отображения (в зависимости от формата). Например, для экспорта в Word доступны три темы оформления, а готовый документ представлен в виде идеально отформатированного файла, со стилями, заголовками, списками, гиперссылками. Работать с таким одно удовольствие, особенно если помнить о том, сколько времени нужно потратить на подобное форматирование в Word вручную.

Также интересна функция экспорта всех скриншотов в папку. При этом Clarify сохраняет все используемые в документе изображения в заданной папке и дает каждому файлу название, соответствующее заголовку раздела, к которому он прикреплен.

⇡#Dr.Explain 5.3 – полуавтоматические руководства с готовыми аннотациями

• Разработчик: Indigo Byte Systems.
• Операционная система: Windows.
• Распространение: shareware, от 7 500 рублей.
• Русский интерфейс: есть.

Dr.Explain не может похвастаться таким современным интерфейсом, как Clarify, однако у этой программы есть свои уникальные особенности. Пожалуй, самое главное – это автоматизация процесса создания технической документации. Просто укажите окно приложения или же веб-страницу сервиса, которые нужно описать, и Dr.Explain самостоятельно создаст скриншот, проанализирует все элементы интерфейса, добавит выноски и даже подпишет их там, где это возможно.

Если в интерфейсе захватываемого приложения встретится меню, Dr.Explain обязательно раскроет его, сделает снимок всех уровней подменю и добавит выноски для каждого элемента. Более того, все скриншоты будут помещены в проект Dr.Explain с сохранением структуры документа (то есть, скажем, основное окно будет в разделе 1, раскрытое меню – 1.1, а пункты подменю – 1.1.1, 1.1.2 и так далее). Таким образом, вся скучная и монотонная работа выполняется в автоматическом режиме, и пользователю остается только добавить описание всех элементов интерфейса. Понятное дело, что структуру документа можно изменять, перемещая пункты, добавляя новые и удаляя ненужные.

Еще до создания скриншотов можно настроить множество параметров, которые касаются изображений. Например, есть возможность задать место размещения выносок, стиль аннотаций, определить вариант генерирования имен файлов (в соответствии с заголовками разделов или их номерами).

Если ранее работа над документацией велась в другом приложении, можно легко импортировать проект и программу. Dr.Explain поддерживает импорт документов CHM, Word, HTML, HLP, RTF, TXT, XML.

Совместная работа над документацией организована через сервис Tiwri.com, созданный специально для обмена данными между пользователями Dr.Explain. Из окна программы можно загружать текущий проект на сервер, отсылать изменения, сбрасывать правки, отслеживать историю.

Для экспорта готовой документации предлагаются форматы CHM, Word, HTML и PDF. При этом еще до выполнения экспорта можно увидеть, как мануал будет выглядеть в одном из этих форматов. Перед экспортом нужно не забыть перейти в настройки проекта и задать дополнительные параметры. Например, при сохранении документа в PDF можно указать ключевые слова, автора, заголовок, тему и формат, настроить колонтитулы и нумерацию страниц, а также создание закладок для разделов. При экспорте в HTML есть возможность настроить карту сайта, добавить комментирование для пользователей Facebook* и Disqus, включить показ панели с кнопками социальных сетей, указать данные FTP-сервера, на который будет загружен проект.

Наконец, стоит обратить внимание на то, что Dr.Explain – продукт отечественных разработчиков, поэтому вполне ожидаемо, что в нем можно найти полноценную поддержку русского языка.

⇡#Manula – перенос мануалов в онлайн

• Разработчик: Bitz & Pixelz.
• Операционная система: любая.
• Распространение: по подписке (от $10 в месяц).
• Русский интерфейс: нет.

В начале 2009 года Альвин Хогердайк (Alwin Hoogerdijk), создатель семейства приложений для учета коллекций Collectorz.com, решил создать для своих программ онлайновую справку. Ему надоело, что часто приходится откладывать выпуск новых версий программ из-за того, что еще не готовы изменения в пользовательской документации, или же, наоборот, делать новые релизы доступными для скачивания с устаревшими справочными файлами, а затем выпускать новые билды, в которых обновлены только мануалы.

Для того чтобы сделать процесс дополнения документации более удобным для разработчиков, а доступ к ней – более быстрым для пользователей, Альвин хотел перенести все в онлайн. Он начал поиск специализированной системы управления контентом, предназначенной для создания технической документации. И когда оказалось, что ничего подобного не существует, разработчик создал собственную систему для своего семейства приложений. Позже она была превращена в более универсальный коммерческий продукт Manula.com.

Manula.com дает возможность создавать и обновлять мануалы в браузере, без необходимости использования настольных приложений. Главное преимущество онлайнового мануала – мгновенное обновление. Как только разработчики внесли в него изменения, обновленные справочные файлы уже становятся доступны пользователям — не надо ничего никуда экспортировать, загружать на сервер HTML-файлы и так далее. При этом мануалы смотрятся одинаково хорошо на любых устройствах – на больших мониторах, планшетах или смартфонах. Сервис автоматически выполняет адаптацию под размер экрана.

А если пользователь захочет получить копию руководства для офлайн-просмотра, сделать это совсем несложно. Manula предлагает удобное скачивание мануалов, созданных на ее платформе, в формате PDF.

В Manula также встроены инструменты для учета изменений и получения отзывов от пользователей. Им предлагается оценивать отдельные темы справочной документации. Для разработчиков есть наглядная статистика оценок и числа посещений разных разделов мануала. Благодаря этому всегда можно понять, в каком месте мануал необходимо доработать, сделать более подробным или связать с другими разделами.

Мануалы, созданные при помощи Manula, имеют интегрированную систему поиска — учитываются заголовки разделов, содержимое документации, а также заданные разработчиком ключевые слова. Сервис сохраняет историю поисковых запросов и показывает разработчикам популярные запросы, благодаря чему можно легко внести изменения в заголовки и ключевые слова.

Одна из интересных особенностей Manula – функция Topic Sharing. Если у компании есть несколько однотипных продуктов, то отдельные фрагменты справки можно сделать для нихобщими. Главное отличие от простого копирования готовых фрагментов документации в том, что при использовании функции Topic Sharing вносить изменения нужно лишь в одном месте. При этом во всех приложениях документация будет обновляться автоматически. Еще больше автоматизировать процесс помогают переменные (например, {APPNAME}), которые настраиваются отдельно для каждого руководства пользователя.

Общие фрагменты справки могут использоваться и для создания отдельной документации для разных версий приложения. Чтобы пользователи не тратили время на поиск функций, которых у них нет, можно сделать отдельные мануалы для каждой версии. При этом основная часть справки будет управляться при помощи функции Topic Sharing.

Встроенного инструмента для создания снимков экрана в Manula нет – придется загружать готовые картинки в библиотеку изображений (она общая для всех проектов) и затем вставлять в нужные места документации. Добавление текста тоже выполняется в онлайновом редакторе, и тут разработчики сервиса смогли придумать кое-что интересное. Наряду с использованием визуального редактора предлагается работать с кодами Textile для ускорения процесса форматирования. Эти коды дают возможность форматировать текст без необходимости обращения к кнопкам редактора. Например, если текст нужно выделить, его просто нужно заключить в две звездочки (*вот так*), а для создания заголовка первого уровня достаточно написать в начале строки h1-.

⇡#StepShot – снимет, расставит по порядку и подпишет

• Разработчик: StepShot.
• Операционная система: Windows.
• Распространение: по подписке ($29 в месяц). Есть полнофункциональная триал-версия на 14 дней, которая затем становится ограниченной.
• Русский интерфейс: нет.

Практически каждое руководство пользователя обязательно содержит инструкции, поясняющие, какие шаги нужно сделать, чтобы добиться заданного результата. Читать такие руководства, где каждый шаг сопровождается скриншотом и пояснением, одно удовольствие, а вот их создание нередко растягивается на долгие часы. Некоторые технические писатели сначала пишут текст, а затем делают все скриншоты и вставляют в нужные места, другие предпочитают делать скриншоты по одному, вставлять их в руководство и тут же добавлять описание. В любом случае, получается достаточно трудоемко.

StepShot – отличная программа, помогающая заметно ускорить создание пошаговых инструкций. Она помогает быстро сделать все скриншоты, не отвлекаясь на сохранение и вставку, располагает их в нужном порядке, помогает добавить описание и аннотации, а затем опубликовать в одном из популярных форматов.

Работа в StepShot построена в виде мастера. Нужно создать новый проект, а затем запустить процесс захвата и начинать выполнять те действия, которые подлежат документированию. При каждом клике мышью программа будет создавать скриншот и сохранять его. При этом на экране постоянно находится панель StepShot, при помощи которой можно остановить процесс захвата и поменять режим снятия скриншотов (весь экран, активное окно, выделенная прямоугольная область).

Эта панель, понятное дело, на скриншотах не видна. В зависимости от настроек, захват может выполняться только тогда, когда щелчок совершается при нажатом CTRL (или другой удобной клавише) или, наоборот, во всех случаях, кроме тех, когда пользователь удерживает заданную клавишу нажатой. В настройках программы также можно задать задержку между кликом и созданием скриншота.

Когда процесс создания инструкции будет завершен, все полученные изображения откроются в окне StepShot. Слева расположена панель навигации с эскизами изображений, справа – скриншот, над которым ведется работа, а также область для добавления описания. Скриншоты уже расставлены в том порядке, в котором они были сделаны, однако при необходимости их можно менять местами, перетаскивая мышью. Кроме этого, каждый шаг (скриншот с описанием) можно копировать или удалять, а также добавлять перед ним пустой шаг, для которого можно, например, импортировать изображение с диска.

Если инструкция объемная, имеет смысл разбить ее на разделы, добавляя разделители в нужных местах. Для каждого раздела есть возможность задать название. На основе разделов будет автоматически сгенерировано оглавление, которое расположится в начале руководства.

Обычно при создании руководств много времени тратится на то, чтобы выделить область, в которой находится курсор на скриншоте (как правило, место, куда нужно кликнуть). StepShot дает возможность автоматизировать и это рутинное действие. Элемент интерфейса, по которому выполняется щелчок мышью, может быть автоматически выделен красным прямоугольником или же желтым кругом. Кроме этого, программа может автоматически сглаживать края скриншотов.

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

Добавление описаний тоже максимально автоматизировано. Поскольку при написании технической документации чаще всего используются одни и те же словосочетания, программа снабжает скриншоты описаниями вроде «Click on «Skype» button». Для этого она захватывает названия элементов интерфейса, распознает их и затем добавляет в подпись под картинкой. Работает это, правда, только для английского и парочки других европейских языков, а составителям русскоязычной документации придется добавлять все описания вручную.

Возможности форматирования в StepShop базовые – можно менять размер шрифта для заголовков скриншотов и их описаний, выделять текст полужирным, курсивом или подчеркиванием, управлять отступами и вставлять гиперссылки. Не стоит забывать о том, что перед выполнением экспорта для проекта можно добавить описание и автора.

После того как работа над созданием руководства завершена, можно экспортировать его в один из нескольких поддерживаемых форматов: документ Word, PDF, HTML, DITA или XML. При этом для Word доступно несколько разных шаблонов.

Также есть прямая публикация на WordPress и в Confluence, а все изображения, использованные в проекте, предлагается сохранить в одной папке. К сожалению, при этом можно управлять только качеством картинок, а вот менять названия нельзя. Скриншоты сохраняются с названиями типа image0001.jpg, image0002.jpg, что не всегда удобно (было бы неплохо, если бы была возможность именования изображений на основе заголовков в проекте).

Несмотря на то, что StepShot распространяется на платной основе, работать с программой можно бесплатно, если вы готовы смириться с водяным знаком на полученных изображениях. Кроме этого, бесплатная версия позволяет создавать до пяти экспортируемых проектов в месяц.

⇡#iorad – аналог StepShot, но в браузере

• Разработчик: iorad inc.
• Операционная система: любая.
• Распространение: по подписке ($90 в месяц). Есть ограниченная бесплатная версия.
• Русский интерфейс: нет.

Для начала работы с iorad нужно установить расширение для Google Chrome и открыть веб-страницу, действия на которой должны быть задокументированы. После этого автору нужно нажать на кнопку расширения. В веб-сервисе iorad применён тот же подход, что и в StepShot (автор инструкции выполняет все действия, сервис их сохраняет, разбивает на шаги, которые затем можно отредактировать и опубликовать в виде урока). Однако iorad работает как расширение к браузеру, и все действия по обработке, редактированию и публикации пошаговых инструкций выполняются на сервере. С одной стороны, это удобно, так как сервис доступен на любой платформе, однако есть досадное ограничение – с помощью iorad можно записать только действия, выполняемые в браузере. То есть сервис подходит только для создания мануалов веб-приложений, а для настольных программ не годится.

После нажатия iorad даст три секунды на подготовку, после чего начнется запись. Сервис распознает и сохраняет любые действия – щелчок мышью, двойной щелчок, прокручивание окна, набор текста и так далее. Когда запись инструкции будет завершена, нужно просто еще раз нажать на кнопку расширения на панели Chrome. Процесс также можно приостанавливать на время, а затем возобновлять.

Когда запись будет завершена, iorad восстановит все действия пользователя и разобьет инструкцию на шаги. Все элементы интерфейса, которые были задействованы, будут выделены (например, кнопка, по которой нужно кликнуть). Кроме этого, iorad автоматически добавляет простые текстовые инструкции для каждого шага.

Каждый урок начинается предложением «The first step is to open [название вебс-страницы]», а заканчивается фразой «That’s it. You’re done.» Несмотря на то, что описания автоматически составляются только на английском, в готовой инструкции есть возможность увидеть их на других языках за счет интеграции с переводчиком Google. Если не добавлять пространных описаний, а ограничиться простыми фразами, такой перевод работает сносно.

Впрочем, если потратить немного времени, можно сразу же добавить описание на родном языке. Однако стоит помнить, что длина описания ограничена 250 символами. В нем можно использовать разные варианты начертания шрифта, а также гиперссылки. Кроме этого, для каждого шага можно добавить аудиоинструкцию продолжительностью до одной минуты. Ее можно записать непосредственно в интерфейсе веб-приложения или же загрузить из имеющихся на компьютере файлов.

Что касается инструментов для редактирования снимков экрана, то тут создателям iorad еще есть над чем работать. Все, что может делать пользователь, это смазывать часть изображения, а также изменять размер и местоположение рамки для выделения.

Готовые инструкции могут быть сохранены в виде файлов Word Doc, PowerPoint и PDF, а также внедрены на сайты или просмотрены в браузере на любых платформах, как настольных, так и мобильных. Используя последние два варианта, можно оценить главное преимущество iorad – интерактивность. Инструкция, полученная с помощью сервиса, запускается в специальном плеере. Пользователь может выбрать один из вариантов работы с ней: просмотр или же самостоятельное повторение всех шагов.

В первом случае все скриншоты и описания к ним выводятся на одной странице, и можно просто прочитать, что делать. Во втором случае пользователю предлагается повторить все действия автора, чтобы достичь нужного результата. То есть он читает описание к скриншоту, выполняет действие и только после этого переходит к следующему шагу. Отличное решение, чтобы убедиться в том, что пользователь действительно понял, что ему нужно сделать.

⇡#Заключение

Специализированные программы для создания мануалов могут заметно ускорить создание технической документации. Однако то, насколько понятным, подробным и структурированным будет файл справки, полностью зависит только от его составителей.

Работая над документацией, стоит всегда помнить о «принципе Златовласки»: пользователю надо давать не слишком много информации, не слишком мало, а в точности столько, сколько нужно для выполнения задач. Хорошая документация должна работать как навигатор: как только пользователь показал, в каком месте он находится (с какой проблемой столкнулся), он тут же должен при помощи файла справки отыскать правильный путь (решение проблемы). И конечно, не стоит забывать о гиперссылках, при помощи которых нужно обеспечивать свободное перемещение пользователя по мануалу. Если в его руках подробнейший PDF на 100 страниц, в котором нет никаких ссылок, качество такой документации вряд ли может оценить кто-то, кроме ее составителя.

Впрочем, современные средства для создания справочных руководств столь разнообразны и многофункциональны, что создавать подробную, понятную и отлично оформленную документацию с их помощью совсем несложно.

* Внесена в перечень общественных объединений и религиозных организаций, в отношении которых судом принято вступившее в законную силу решение о ликвидации или запрете деятельности по основаниям, предусмотренным Федеральным законом от 25.07.2002 № 114-ФЗ «О противодействии экстремистской деятельности».

Автор: Виктор Амосов, аналитик компании Индиго Байт, которая разрабатывает программу для управления технической документацией.

В наше время тестировщика часто заставляют писать техническую документацию к продукту. И на это есть ряд очевидных причин. Тестировщик как никто другой знаком с функционалом ПО, знает все его тонкости, знаком со всеми проблемами и ошибками. Но тестировщик — не писатель, а документация, которую будет читать пользователь, должна быть понятна и легко читаема. Так как же написать качественную документацию, которая будет отвечать всем запросам пользователей? 

Данная статья предлагает правила написания и проверки технической документации, а также инструменты, для упрощения работы «технического писателя».

Советы по созданию пользовательской документации

Мы стремимся создавать документацию, которая будет полезна. То есть мы хотим, чтобы наши пользователи оперативно находили нужные разделы и применяли их для решения своих задач при работе с программным продуктом. Я опираюсь на девять эмпирических правил или эвристик удобства использования  документации при разработке, оценке и правке технического контента до того, как документация будет опубликована. Применение этих эвристик может помочь техническим писателям не совершать классических структурных ошибок и даст более глубокое понимание того, как пользователи работают с  документацией.

Правила качественной документации, описанные в этой статье, основываются на десяти основных принципах юзабилити в дизайне, разработанных Jakob Nielsen и Rolf Molich в 1990 году. Однако — мне пришлось переработать многие из них на основе собственного опыта по оценке качества документации.

1.  Поиск и навигация

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

У пользователя должна быть возможность находить нужный раздел, пользуясь поиском или перемещаясь по оглавлению. Если требуется прочитать несколько разделов, переход между ними должен быть простым.

2. Ориентирование

В любой момент пользователь должен понимать, в какой части документации он находится и где он был перед этим. Выстраивайте разделы так, чтобы их логика соответствовала логике пользователя и логике выполнения сложных задач.

Как понять логику пользователя? На самом деле, тут точного ответа нет, но есть базовые вещи, в которых писатели до сих пор совершают ошибки. Вряд ли пользователю сразу понадобится контактная информация вашей компании, так что ее лучше разместить в конце, а вот разделы с объяснением элементов интерфейса и описанием возможностей программы поместите в начале.

Поставьте себя на место пользователя. С какой проблемой он столкнется в первую очередь, какие затруднения будут потом, и примерно в таком порядке составляйте руководство.

3. Решение задач

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

4. Обобщение задач

Пользователь должен быть способен экстраполировать информацию из документации на ситуации, которые не задокументированы явным образом. Например, он должен понимать, как входные данные соответствуют различным режимам работы программы.

Нецелесообразно описывать в руководстве похожие ситуации по отдельности, так как оно станет громоздким и трудночитаемым. Обобщите и напишите об одном так, чтобы пользователь смог понять и применить полученные знания на похожие случаи.

5. Диагностика ошибок и устранение их последствий.

Пользователя надо научить не бояться проблем и решать их.

Говорить о своих проблемах – лучше, чем умалчивать…

В каждой программы возможны баги… Вы знаете о них, но пока нет времени исправлять? Лучше напишите и предупредите пользователя. Следуя моему опыту, лучше «признать» ошибку и показать себя, возможно, не с лучшей стороны, чем промолчать и потом терять клиентов из-за их неоправданных ожиданий. Если у пользователя будет инструкция по ликвидации проблем – он вряд ли задумается о смене программы.

Ну и, конечно же, создайте раздел в руководстве с контактами технической поддержки и ее режимом работы, чтобы пользователь мог обратиться за помощью.

6. Соответствие между документацией и реальным миром с точки зрения терминов и концепций

Чаще всего документацию к продукту пишут те, кто его создает или тестирует. Это логично и нормально, но не стоит забывать, что читать ее будут другие люди, которые, скорее всего, далеки от программирования. Им будут не понятны такие слова и выражения: деплой, релиз, инкапсуляция и так далее.

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

7. Писательский минимализм

Следует избегать ненужной и иррелевантной информации. Каждый дополнительный блок информации в документации будет конкурировать за пользовательское внимание. Это осложнит пользователю поиск нужной информации.

8. Согласованность и стандарты.

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

Если что-то принято называть «разделом», то надо придерживаться этого термина, и не использовать альтернативы — «секция, топик, тема».

9. Интеграция с программным продуктом.

Пользователю грустно видеть программу, в которой он не может открыть «файл-помощник»!

Пользователь не должен прерывать процесс работы в программе для того, чтобы обратиться к документации. Старайтесь реализовать функцию поиска по документации прямо из программы, а также сделайте контекстно-зависимую справку.

А вообще, документация должна быть многоформатной! Пользователь может читать документацию и не работая в программе, поэтому следует загрузить документацию на сайт, тем самым сделав online-справку. Также стоит разместить на сайте PDF версию документации, для случаев, если у пользователя нет доступа к интернету.

Мини-итог

Прежде чем проводить оценку документации, определитесь с предполагаемой целью, которую многие пользователи пытаются достичь с помощью программного продукта. При этом неплохо удостовериться, что эта цель, стоящая перед большинством пользователей, согласуется с целью, которую компания-разработчик закладывала в продукт. Например, компания производит, как она полагает, «программу для моделирования», в то время как пользователь хочет «моделировать контроллеры».

Запустите программу. Затем решите задачу как обычный пользователь, пользуясь документацией. Вы также можете привлечь пару друзей для этого. Поскольку ваши приятели скорее всего меньше знакомы с вашей документацией, имитировать обычных пользователей и их работу в программе у них получится гораздо лучше. 

Инструменты для быстрого создания руководства пользователя

Используя вышеперечисленные советы, думаю вам станет проще писать документацию, но кроме вопроса КАК писать документацию еще важен вопрос ГДЕ.

Я много лет «кручусь» в области технического писательства, потому что создаю и модернизирую свой собственный продукт для создания качественных «хэлпов»

И на правах рекламы мне хочется о нем рассказать. Возможно именно с ним вам станет проще создавать и поддерживать пользовательскую документацию. Понимаю, что рекламные части статей отталкивают читателей, поэтому я постараюсь сделать его кратким и лаконичным.

Далее вы ознакомитесь с некоторыми возможностями программы для создания руководства пользователя – Dr.Explain.

1. Аннотирование

Часто техническим писателям при документировании пользовательского интерфейса приходится снабжать изображения пояснительными выносками. Для того, чтобы этот процесс стал проще и быстрее программа умеет автоматически аннотировать изображения. Это значит, что при создании скриншота программа проанализирует структуру окна и добавит пояснительные выноски к значимым элементам. (по ее мнению конечно же) Но вы также сможете добавлять аннотации к скриншоту или фотографии самостоятельно – для этого есть специальный редактор аннотирования скриншотов.

2. Шаблоны

Гораздо проще работать по образцу. Для этого в Dr.Explain есть шаблоны руководств пользователя. В них разделы уже частично заполнены текстовым и графическим контентом. В некоторых случаях писателю, работающему в шаблоне, нужно будет только вставить текст из разряда: название программы, имя компании или адрес технической поддержки. В программе на данный момент есть три шаблона – для ПО, для WEB-сервиса и для корпоративной базы знаний.

3. Многоформатность.

Я говорил уже о том, что документация должна быть многоформатной, и это не моя прихоть, а требование эпохи. Например, для того, чтобы программе попасть в Реестр Отечественного ПО, сейчас обязательно наличие онлайн-документации.

В Dr.Explain, имея текстовый документ, вы сможете:

— экспортировать его на сайт продукта в формате HTML, тем самым создать online-справку;

— сделать контекстно-зависимую справку в формате CHM для интеграции с ПО;

— экспортировать текст в формат PDF для создания «печатной» документации;

В программе множество функций для облегчения работы по написанию документации. Вы можете ознакомиться с ними по адресу: https://www.drexplain.ru/features/

Скачать Dr.Explain бесплатно можно по адресу: https://www.drexplain.ru/download/

Подытожим

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

Успешных вам разработок!

Обсудить в форуме

Когда вы имеете дело с веб-приложением или сайтом, который нуждается в онбординге пользователей, хорошей практикой считается использовать пошаговые руководства, интерактивные подсказки или туры по продукту, которые обеспечат достойный первый опыт и снизят отток. 

В этой статье мы рассмотрим 28 полезных плагинов, позволяющих создавать такие руководства.

Примечание: если у вас нет времени или денег на разработчиков, попробуйте поработать с нашей онбординг-платформой Experrto. Мы упростили создание интерактивных подсказок настолько, что с этим сможет справиться любой член вашей команды.

Содержание статьи

1. Intro.js
2. Website Tour with jQuery
3. JQuery joyride feature tour plugin
4. Bootstro.js
5. JQuery myTour plugin
6. Crumble
7. Trip.js
8. FAQtoid
9. JQuery Tour Bus
10. Feature Walkthrough
11. Chaperone.js
12. Hopscotch
13. Pageguide.js
14. aSimple Tour Plugin
15. Bootstrap Tour
16. TourTip – jQuery Overlay Tour
17. JQuery Tour
18. Website tours with jQuery UI
19. Bon Vojage
20. ddTour
21. Quicktour.js
22. LightsOff.js
23. Usertour.js
24. VTour.js
25. jQuery-guide
26. Concierge
27. Anno.js
28. EnjoyHint
Подсказки без кодинга

1. Intro.js

Этот простой и быстрый javascript-плагин позволяет создавать пошаговые инструкции для сайтов, приложений и новых функций.

2. Website Tour with jQuery

Это небольшой скрипт, предназначенный для создания онлайн-туров на сайтах с помощью jQuery. Он может вам пригодиться, если вы хотите объяснить пользователям функционал вашего приложения через интерактивные подсказки.

3. JQuery joyride feature tour plugin

Joyride — это чрезвычайно гибкий плагин, который позволяет вам контролировать то, как пользователь взаимодействует с вашим туром.

Какой UI-шаблон лучше всего подойдет вашему туру по продукту?

4. Bootstro.js

Bootstro.js — это крохотная JS-библиотека, которая помогает направлять пользователей в рамках тура по продукту за счет всплывающих окон bootstrap.

5. JQuery myTour plugin

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

6. Crumble

Crumble позволяет легко и быстро создавать функциональные туры для сайтов или приложений с помощью небольших «пузырьков». Такие сообщения привлекают внимание, но чтобы они оставались читабельными, их нужно заполнять как можно более кратким текстом.

Искусство онбординга, или Зачем нужен процесс адаптации к продукту?

7. Trip.js

Trip.js — это плагин, который может помочь вам сделать ваше онбординг-руководство более гибким. Сейчас он поддерживает множество полезных возможностей, таких как бинды для клавиатуры, анимации, изменение тем и т. д.

8. FAQtoid

FAQtoid — это простая универсальная help-система для вашего сайта или приложения. Она помогает уменьшить затраты на клиентскую поддержку, предоставляя посетителям инструменты для решения их проблем.

• FAQ с live-поиском — пользователи видят ответы по мере ввода запроса;
• Туры — проводят пользователей по элементам каждой страницы;
• Видеогалерея — пользователи могут смотреть видео, оставаясь на странице, которая в нем поясняется;
• Умная email-форма — обрабатывает нежелательные сообщения. Автоматически включает подробную информацию о вашем пользователе, о том, что они пытались сделать, и любых ошибках на странице.

9. JQuery Tour Bus

Это плагин для разработчиков, позволяющий создавать онлайн-туры. Он весьма ограничен в плане автоматизации и больше походит на набор инструментов.

Как адаптировать приглашенных пользователей к SaaS-продукту?

10. Feature Walkthrough

Это JS-плагин для добавления пошагового руководства на веб-странице. В настройках вы можете выбрать позиционирование сообщений: слева, справа, вверху или внизу от элемента, который описывается. Для размещения элемента справа/слева вам нужно указать ширину, вверху/внизу — высоту.

11. Chaperone.js

Chaperone — это простой плагин, позволяющий создавать экскурсии по сайту. Подобно Joyride он использует список элементов и проводит пользователей по ним с помощью сообщений.

12. Hopscotch

Hopscotch — это фреймворк, который позволяет разработчикам без особых усилий добавлять туры на страницы своего сайта. Hopscotch использует JSON объекты в качестве входных данных и предоставляет вам API для управления отображением тура и его прогрессом.

6 примеров чек-листов для продвинутого онбординга

13. Pageguide.js

Pageguide.js — интерактивное визуальное руководство для элементов веб-страниц. Вместо того чтобы загромождать ваш интерфейс статическими вспомогательными сообщениями или пояснительным текстом, добавьте на сайт Pageguide и позвольте вашим пользователям изучать новые возможности и функции.

14. aSimple Tour Plugin

В то время как всплывающая панель aSimple Tour Plugin позволяют управлять туром, подсказки, которые могут размещаться где угодно, помогают пользователям сфокусироваться на конкретных элементах сайта.

15. Bootstrap Tour

Этот плагин проводит пользователей по сервису с помощью всплывающих окон Bootstrap и отличается гибкими настройками.

Для чего нужен навигатор интерфейсов?

16. TourTip – jQuery Overlay Tour

TourTip — это простая библиотека для создания туров по сложным одностраничным веб-приложениям. Она дает вам возможность настраивать шаги процесса таким образом, чтобы переходы между ними выполнялись не только спустя несколько секунд, но и после того, как пользователь завершит поставленную задачу.

17. JQuery Tour

С помощью этого плагина вы можете создавать отличные туры по продукту. Если вы попросите пользователя выполнить конкретное действие, прежде чем он перейдет к следующему шагу, JQuery Tour автоматически скроет все второстепенные элементы страницы.

18. Website tours with jQuery UI

Этот плагин позволяет вам разрабатывать туры по сайтам за счет инструментов для экспонирования и аннотации элементов на веб-страницах. При необходимости процесс можно автоматизировать.

3 принципа разработки эффективных in-app уведомлений

19. Bon Vojage

Bon Vojage — это крохотный JQuery плагин, с помощью которого вы сможете создать простейший тур по сайту.

20. ddTour

Это несложное решение для онлайн-туров, которое было создано Дэвидом Дэвисом (David Davis).

• В отличие от других плагинов, здесь ваш код находится в одном месте. Всплывающая подсказка появляется именно там, где у вас есть ее описание.
• Перемещайтесь к любому элементу с помощью обозначенного селектора класса.

21. Quicktour.js

Quicktour.js использует итеративный цикл, чтобы выделять элементы тура в том порядке, в котором вы их добавляете. На затененной странице появляется рамка с заголовком (если он указан), и пользователь продолжает выполнять процесс с каждым кликом.

Отток как следствие плохого онбординга?

22. LightsOff.js

«Легкий» плагин (всего 6 кб), который позволяет создавать отличные настраиваемые пояснения к различным элементам веб-страницы.

23. Usertour.js

Этот jQuery виджет подходит для веб-приложений, которые хотят предоставить своим пользователям пошаговое руководство.

24. VTour.js

Эта библиотека используется для создания пошаговых инструкций для страниц сайта и его функций.

25. jQuery-guide

jQuery-guide позволяет объяснять пользователям новые макеты и функции, подсвечивая важные элементы страницы на затененном фоне.

26. Concierge

Еще один плагин, которые создает пошаговые инструкции для различных элементов страницы. 

27. Anno.js

Этот плагин также используется для создания эффективных руководств к мощным веб-приложениям.

28. EnjoyHint

Это бесплатный веб-инструмент, который помогает пользователям ориентироваться на сайте легко и интуитивно. Он позволяет вам создавать интерактивные туториалы с подсказками и внедрять их в приложение, тем самым улучшая его юзабилити и эффективность.

20 топовых open source плагинов для всплывающих подсказок

Подсказки без кодинга

Существует множество причин, по которым вы можете захотеть интегрировать руководства в свой продукт, будь то запуск какой-то новой сложной функции, онбординг после регистрации или общее повышение качества UX. 

Однако проблема с использованием бесплатных плагинов заключается в том, что у ваших разработчиков, скорее всего, есть куда более важные задачи, и они просто не могут заниматься еще и кодингом подсказок.

Платформа Experrto позволяет с легкостью создавать руководства без помощи программистов и дизайнеров. Для того, чтобы добавить подсказки на свой сайт, вам достаточно скачать расширение Experrto для Google Chrome и начать управлять подсказками через браузер с помощью простого редактора (виджета).

Подписывайтесь на нашу группу в фейсбуке и канал в телеграм, чтобы следить за обновлениями.

Прокачайте свой онбординг!

По материалам: ninodezign.com Изображение: freepik.com