База знаний 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 наших сервисов.

Что еще почитать по теме

Ульяна Малышева 8 сентября 2022

Продуктовый дайджест: серверы в Сибири и дефицитные A100

Рассказываем о продуктовых обновлениях последнего месяца.
Ульяна Малышева 8 сентября 2022
Михаил Фомин 11 августа 2022

Скидка 25% на миграцию и советы по оптимизации затрат на IT-инфраструктуру

Рассказываем о том, как оптимизировать расходы на IT-инфраструктуру и комфортно мигрировать от зарубежного провайдера со скидкой 25%
Михаил Фомин 11 августа 2022
Андрей Зайцев 10 августа 2022

Продуктовый дайджест: новые серверы, процессоры, бэкапы и Kubernetes 1.24

Скидки на наши услуги, новые конфигурации серверов и ускорение работы бэкапов по расписанию.
Андрей Зайцев 10 августа 2022

Новое в блоге

Михаил Фомин 24 июня 2022

Docker Swarm VS Kubernetes — как бизнес выбирает оркестраторы

Рассказываем, для каких задач бизнесу больше подойдет Docker Swarm, а когда следует выбрать Kubernetes.
Михаил Фомин 24 июня 2022
Владимир Туров 5 октября 2022

DBaaS: что такое облачные базы данных

Рассказываем о сервисе управляемых баз данных в облаке и объясняем, как разделяется ответственность за работу кластеров БД между провайдером и клиентом.
Владимир Туров 5 октября 2022
Ульяна Малышева 30 сентября 2022

«Нулевой» локальный диск. Как мы запустили облако только с сетевыми дисками и приручили Ceph

Чем хороши сетевые диски и почему именно Ceph, рассказал директор по развитию ядра облачной платформы Иван Романько.
Ульяна Малышева 30 сентября 2022
Валентин Тимофеев 30 сентября 2022

Как проходит онбординг сотрудников ИТО? Что нужно, чтобы выйти на смену в дата-центр

Рассказываем, как обучаем новых сотрудников, какие задачи и испытания проходят инженеры прежде, чем выйти на свою первую смену.
Валентин Тимофеев 30 сентября 2022