Главная цель документации

Главная цель пользовательской документации — помочь людям без технических знаний решить проблемы с софтом самостоятельно. К сожалению, наша документация в текущем виде не выполнит главную цель. Я расскажу, почему так произошло, и как это исправить с помощью приложения «Scroll Viewport».

Документация сейчас

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

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

Разберём проблемы документации на примере мобильной версии этой статьи:

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

Огромная кнопка «Открыть это приложение». Внизу постоянно висит кнопка, которая призывает скачать приложение «Confluence Server». Это приложение не нужно пользователям, люди без аккаунта Atlassian не смогут войти в него.

Плагины, которые не работают. Если в статью встроены сторонние макросы, в мобильной версии они не доступны. Даже не все нативные макросы доступны, например нативный плагин с поиском на главной странице не работает.

Вместо макроса пользователям предлагают посмотреть версию для ПК.

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

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

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

Документация + Scroll Viewport

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

Приложение «Scroll Viewport» решает эту проблему, разделяя интерфейс для создателей контента, и для его потребителей. Confluence выступает в роли CMS, а Scroll Viewport контролирует, как контент выглядит для пользователей. Для этого есть готовые темы, на основе которых можно создать собственную, используя HTML, CSS, JavaScript и Velocity.

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

Посмотрите на статью без темы, и с темой:

Посмотрите на новую статью. И на старую статью. Да, новая статья на коне 😀

Пройдемся по преимуществам новой темы:

Навигация по сервисам «Агент Плюс». Не нужно помнить адрес каждого сервиса — всё в одном месте.

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

Заголовок и навигация по разделам.

Для примера навигации по разделам введены хлебные крошки — путь от корневого раздела до статьи. Хлебные крошки помогут перемещаться по разделам руководства.

Заголовок статьи крупнее основного текста и заголовков, набран гарнитурой
Uni Sans из фирменного стиля «Агент Плюс». Документация это маркетинговый инструмент, наряду с сайтом, соц сетями и другой открытой информацией о компании. Придерживаемся единого стиля везде 💪

Заголовок и хлебные крошки адаптивно подстраиваются под ширину экрана

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

Полезный совет изменён с помощью CSS — белый фон не мешает читаемости, толстая рамка привлекает внимание, создаёт контраст. Края рамки скруглены согласно фирменному стилю «Агент Плюс».

Слева — главная страница документации. Справа — статья с выделенным советом.

Правильная типографика и UX.

В новой теме нет лишних кнопок и меню, только полезные для пользователя.

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

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

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

P.S: статья с новой темой на большом экране тоже хороша 😎