База знаний 2.0

С развитием услуг Selectel три года назад для удобства клиентов мы обновили панель управления и объединили все справочные материалы в единую систему — базу знаний.

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

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

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

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

Небольшой экскурс в прошлое

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

В среде технических писателей всё ещё популярен мем:

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

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

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

1. Пользователь заказал услугу.
2. Столкнулся с неочевидными моментами при настройке.
3. Хотел обратиться в техническую поддержку.
4. Зашел в базу знаний и нашел нужную информацию самостоятельно.
5. Не обратился в техническую поддержку.
6. Профит!)

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

Какая задача стояла перед нами

Наше визуальное решение перестало позволять легко находить нужные статьи, и существующее меню превратилось в нечитаемую «простыню». Нечитабельная документация также плоха, как неактуальные тексты. Люди привыкли читать хорошо сверстанные материалы. Блоги, соцсети, медиа — весь контент подается не просто красивым, но и удобным для чтения, приятным для глаза. В настоящее время нельзя игнорировать UX и UI требования, тем более для такого огромного массива текстов.

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

Часто возникающие проблемы с документацией:

• Вообще отсутствует или никто не знает о ее существовании.
Инструкция, которую нельзя найти, ничем не лучше инструкции, которой нет.

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

• Устаревает и вовремя не актуализируется.
Процесс документирования не встроен в разработку продукта, документация делается по остаточному принципу.

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

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

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

Как это работает теперь

Техническая реализация

Первоначально база знаний была построена на основе объединения Confluence и генератора статических страниц.

Мы отказались от Confluence и перешли к принципу Documentation-as-Code.

Сейчас все исходные тексты для базы знаний верстаются в формате Markdown и хранятся в системе хранения версий Git. Из хранилища с помощью генератора статических сайтов Hugo собирается сайт базы знаний. Сайт генерируется из файлов, содержащихся в master-ветке Git-репозитория. Обновить данные можно только через pull-request, что позволяет проверять все новые разделы документации перед тем, как они будут опубликованы в общем доступе. Такая система также облегчает подход к внесению правок — сотрудники компании всегда могут создать ветку и добавить в нее все нужные изменения.

Подробнее о Documentation as Code

Принцип «документация как код» подразумевает использование при написании документации того же инструментария, что и при создании кода:

• языки разметки текста;
• системы контроля версий;
• code review.

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

Визуальная составляющая

Первым делом требовалось пересмотреть навигацию и создать правила, по которым бы формировались разделы базы знаний. Совместно с UX-проектировщиками мы подготовили информационную архитектуру. Структура должна быть максимально прозрачной, чтобы читатель не задумывался: «А где можно найти эту статью?». Если обобщить, то есть два подхода:

• От интерфейса. Содержание дублирует разделы панели (отдельно по услугам). Так было в предыдущей версии базы знаний.
• От задач. Названия статей и разделов отражают задачи пользователей.

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

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

Вместо заключения

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

(Льюис Кэрролл «Алиса в Зазеркалье»)

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

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