Да, будет код: как мы провели редизайн базы знаний

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

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

В 2019 году мы заметили, что online-справка перестала отвечать требованиям наших клиентов из-за:

• слишком обширного меню навигации,
• неудобного поиска,
• устаревшего внешнего вида.

Мы решили провести тотальный редизайн, поменять концепцию и перезапустить базу, используя популярный сегодня принцип Docs-as-Code. Вот, как это было.

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

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

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

   Наше решение:

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

   — включили переходы на продуктовых страницах сайта,

   — наладили оповещение всех заинтересованных сотрудников компании через специальный канал в корпоративном мессенджере.

2. #БазаЗнаний устаревает и вовремя не актуализируется. Процесс документирования не встроен в разработку продукта, документация делается по остаточному принципу.

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

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

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

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

Цели БЗ для клиентов:

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

Цели БЗ для сотрудников:

• для обучения/шпаргалки,
• для быстрого поиска необходимой клиенту инструкции.

В итоге, наш проект состоял из двух частей: технической стороны и визуального решения.

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

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

Все исходные тексты для базы знаний мы верстаем в формате Markdown и храним в Git-репозитории.

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

Нашу новую базу знаний мы устроили по принципу Documentation-as-Code. Этот подход подразумевает использование при написании документации того же инструментария, что и при создании кода: языков разметки текста, систем контроля версий, code review.

Основные преимущества Docs-as-Code в следующем.

1. Коллаборация с разработчиками: многие из них предпочитают работать прямо в текстовом редакторе в формате Markdown.
2. Обновление без предела: можно редактировать десятки страниц и вносить код в свой репозитарий, нет необходимости разворачивать что-то вручную.
3. Тесная связь с участниками процесса: благодаря работе с контентом в одном и том же Git-репозитории.
4. Гибкость и контроль по отношению к среде.

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

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

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

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

В итоге мы применили комбинацию двух подходов.

Мы действуем по принципу “один продукт = один раздел БЗ”. При открытии вкладки “Серверы” теперь увидим следующее окно.

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

Допустим, вы решили провести диагностику сервера. Идем по пути “Серверы” — “Инструкции” — “Как провести диагностику сервера”. Хлебные крошки покажут ваш путь поиска и дадут возможность вернуться на любой из предыдущих уровней. Решили познакомиться с бета-версией услуги Managed Kubernetes, но плохо разбираетесь в терминах? У нас есть глоссарий, где все подробно объяснено.

В итоге вот, что изменилось.

• Появился рубрикатор по продуктам на главной странице. Можно сразу перейти в раздел о конкретном сервисе.
• Добавили быстрый поиск с подсказками по ключевым словам. А также теперь работают похожие запросы и опережающий поиск.
• Изменили поиск, он не уезжает под “шапку” сайта при скролле страницы, как это было раньше.
• Сделали поддержку разных разрешений экрана для комфортной работы. Сейчас удобно пользоваться базой знаний с мобильных устройств.
• Улучшили читаемость текста: шрифт стал крупнее, отступы более сбалансированы.
• Обновили заголовки — сделали их более понятными, ведущими к соответствующим инструкциям и разделам.

Если вы увидели, что еще мы можем изменить/дополнить в базе знаний или хотите поделиться с нами ссылками на другие удобные и классные справочники, пишите комментарии или присылайте письма на [email protected].

Только Selectивный отбор. Не только Hardcore, но и Cloud.

Ваш Selectel

Понравился материал?

Подписывайтесь и следите за обновлениями:

vc.ru, FB, Vk, Instagram, Twitter, Youtube, Habr, блог.

#selectel