Платформы для автоматизации бизнес-процессов (BPA) предлагают широкие возможности по интеграции и автоматизации, но их освоение может быть непростым даже для опытных специалистов. В этой статье мы рассмотрим пример руководства пользователя сервиса автоматизации Camunda. Посмотрим, что можно перенять для своего проекта, и обратим внимание на ошибки, допущенные разработчиками.
База знаний состоит из шести больших разделов:
- Get started;
- Using Camunda;
- Self-Managed;
- APIs and tools;
- Best Practices;
- General reference.
Мы рассмотрим раздел Using Camunda, который находится по адресу: https://docs.camunda.io/
Особенность пользовательской документации заключается в том, что это проект с открытым исходным кодом, располагается он на Github, где для каждой версии создана отдельная папка:
Оценим по пяти критериям:
- структура;
- навигация;
- содержание;
- оформление
- обратная связь и обновления.
На самом деле, критериев могло быть больше, но мы сосредоточились на выявлении интересных решений и ключевых недостатков, чтобы извлечь уроки для будущих проектов.
Структура руководства пользователя
Структура пользовательской документации — это каркас, который во многом влияет на то, найдет ли пользователь ответ или утонет в непролазном хаосе. В данном случае авторы учли, что Camunda Platform 7 и Camunda Platform 8 — это две разные платформы с разной архитектурой и подходами, поэтому разбили документацию на соответствующие разделы. Уже хорошо.
Сложно сказать, насколько логична предложенная иерархия, однако при беглом взгляде создается впечатление, что путаницы возникнуть не должно.
Вложенности глубже пяти разделов обнаружить не удалось — похвально, учитывая сложность системы.
Эффективность структуры оценивается по нескольким критериям, в числе которых:
- предсказуемость — пользователь интуитивно понимает, где искать;
- адаптивность — структура развивается с продуктом (есть версионирование, создаются новые разделы, улучшаются старые);
- гибкость — возможность добавить раздел без разрушения логики, иерархии.
Справочная база Camunda предсказуема и адаптивна. Что касается гибкости, её эффективность можно оценить только имея опыт поддержки этого большого проекта. В целом, можно сказать, что структура Camunda соответствует основным требованиям к качеству.
Навигация руководства пользователя
Если документация — это город знаний, то навигация — это дорожные знаки, карты и указатели. Можно ли добраться до цели без них? Теоретически — да. Но сколько времени вы потеряете в тупиках, объездах и пробках? Хорошая навигационные инструменты превращают путешествие в удовольствие, а плохие — в квест на выживание.
Навигация Camunda не вызывает вопросов: здесь присутствуют как стандартные решения, характерные для справочных систем, так и некоторые приёмы, которые редко встречаются в руководствах пользователя.
Например, в каждом разделе справа присутствует интерактивное меню, которым авторы справочных документаций балуют читателя не часто:
Можно окинуть взглядом ключевые моменты раздела и понять, есть ли в нем интересующая информация.
Часть пользователей ищет точечные ответы, минуя сквозное чтение инструкций, поэтому качество поискового движка (релевантность, скорость, автозаполнение, фильтры) имеет для них решающее значение. Формой поиска Camunda такие читатели останутся довольны. Например, здесь предусмотрено не только использование горячих клавиш:
Но и есть предиктивный ввод, а результаты поиска оформляются в виде интерактивной ментальной карты, наглядно показывающей взаимосвязи и иерархию разделов:
Присутствуют хлебные крошки — потеряться будет сложно:
На страницах разделов имеется блок "Related resources" ("Похожие статьи") — как мы писали не раз, это нужно не только для удобства навигации, но и для целостного восприятия материала:
О любителях пошагового изучения инструкций разработчики тоже не забыли:
Ссылки оформлены в виде кнопок, глазу легче за них зацепиться. Сравните с обычным текстовым оформлением, которое теряется на странице среди прочего контента:
В документации используется бот, который облегчает поиск информации. Кнопка вызова ассистента находится в правом нижнем углу:
При нажатии на кнопку появляется окно, в котором можно выполнить обычный поиск или задать вопрос ассистенту. Жаль, что интерфейс ассистента не стилизован в соответствии с темной темой:
В окне с результатами поиска видим отформатированный текст, иконки для дальнейших действий (очистить, копировать, оценить ответ), а также разделы документации с подробной информацией:
Понятие "коннектор" занимает особое место в системе Camunda. Этому термину посвящен целый массив контента, состоящий из нескольких больших разделов. Для удобства разработчики добавили форму поиска с фильтром. Ниже расположены ссылки на разделы оформлены в виде плиток с соответствующей иконкой и кратким описанием.
Получилась документация в документации, и если у вас похожая ситуация (есть некая концепция, требующая особого внимания), стоит разнести контент, посвященный одной большой теме, в отдельные разделы с фильтром, как в примере выше, а не писать все сплошной стеной текста.
Навигация — это ключевой аспект, определяющий удобство и эффективность использования руководства пользователя. В нашем сегодняшнем примере этот аспект продуман и является хорошим гидом по проекту.
Содержание руководства пользователя
Продуманность содержания руководства пользователя — это искусство предугадать путь читателя и, говоря образно, умение расставить фонари именно там, где он может споткнуться. Это не просто список функций, это интеллектуальная карта решения проблем, а ее информативность — еще один параметр оценки качества содержания.
Полноту информации документации Camunda оценить непросто, поскольку для этого требуется определенный опыт пользования сервисом. Зато такая важная вещь, как наглядность, вопросов не вызывает: многие разделы включают примеры кода, диаграммы и скриншоты, что значительно облегчает понимание сложных понятий. Хотя отсутствие видео немного портит общую картину.
Разработчики активно используют блок-схемы:
Авторы применяют разные типы текстовых блоков:
Добавляют скрываемые блоки:
В оформлении таблиц используется заливка строк таблицы "зеброй", мелочь, а приятно:
Обратите внимание, как много перекрестных ссылок. Они связывают похожие модули, помогают ориентироваться в контенте, глубже погружают в материал:
Используются четкие шрифты, достаточный интервал между строками и хорошо структурированные параграфы, что способствует легкому чтению. Применяется форматирование жирным, наклонным:
Некоторые разделы предваряются предупреждением о том, для какой версии актуальна следующая информация:
Способствуют пониманию материала аннотированные скриншоты — без них в хорошей справочной документации не обойтись:
Раздел "Best Practices" предоставляет проверенные подходы и рекомендации по использованию платформы Camunda. Они основаны на опыте компании и сообщества. Инструкции лаконичны, поэтому в основной своей массе страницы не приходится долго скроллить. Однако попадаются чрезвычайно длинные разделы, в которых отсутствие кнопки "Наверх" вызывает желание поставить авторам жирный минус.
Оформление руководства пользователя
Продуманное оформление документации — это инвестиция в удобство пользователя. Оно делает процесс обучения и решения проблем эффективнее и приятнее, что, в свою очередь, повышает удовлетворённость продуктом. Какие особенности мы можем отметить здесь?
Первое, что замечаешь, в оформлении справочной системы Camunda используется темная тема, пока еще не такая распространенная в руководствах пользователя.
И сразу серьезное упущение: изображения не кликабельны, прочитать мелкий текст невозможно:
В некоторых разделах ссылки на связанные материалы оформлены в виде иконок — хорошо, когда контент разбавлен изображениями:
В блоках с примерами кода при наведении появляется иконка, позволяющая скопировать содержимое в один клик:
Страницы этого руководства отличает умеренное и уместное применение интерактивных элементов. Например, мы можем отобразить пример кода, актуального только для определенной операционной системы:
Учитывая множество технических приемов, использованных авторами, обойти стороной адаптивность было бы преступлением. Владельцы планшетов и смартфонов могут быть спокойны: справочная система платформы Camunda приспособлена для чтения на любых экранах.
Обратная связь и обновления руководства пользователя
Обратная связь и обновления — это две взаимосвязанные и важные составляющие успешной пользовательской документации. Без них она быстро устаревает, теряет актуальность. Зато продуманный процесс обновлений превращает документ в динамичный, постоянно развивающийся ресурс, который остается актуальным и полезным на протяжении всего жизненного цикла продукта.
Важно не только собирать отзывы, но и активно их обрабатывать, интегрируя в процесс регулярных обновлений. Синхронизация документации с релизами продукта и ведение подробного журнала изменений поможет пользователям всегда иметь доступ к актуальной информации.
Как с этим обстоит дело здесь?
Поскольку документация Camunda — это проект с отрытым исходным кодом, желающие могут не только поставить ему оценку, но и поучаствовать в его развитии:
Использование Github предоставляет пользователям и разработчикам все прелести версионирования. Похоже, разработчики обновляют файлы регулярно, поэтому читателю можно смело рассчитывать на актуальность информации:
Итог
Документация оставляет приятное впечатление: она всеобъемлюща, наглядна и ориентирована на решение пользовательских задач, а не простое описание функциональности. Её сильные стороны:
- сквозная навигация (хлебные крошки, связанные статьи);
- расширенный поиск;
- наглядность;
- приятный дизайн.
Документация Camunda особенно ценна благодаря многообразию представленных форматов, обилию изображений и интерактивных элементов. Хотя изображения не кликабельны, а видео отсутствует, это нисколько не умаляет её достоинств. Интересно, что она демонстрирует эффективное использование даже базовых решений, которые часто игнорируются в других инструкциях. Это руководство — образцовый пример создания по-настоящему удобной пользовательской документации для сложного продукта, такого как BPA-система. Надеемся, что эта статья вдохновит вас на разработку собственной качественной документации.
Если вы еще не готовы разрабатывать справочную систему с использованием онлайн-сервисов, присмотритесь к софту для десктопной разработки. Скачайте программу Dr.Expain бесплатно и изучите ее возможности прямо сейчас!