Да, будет код: как мы провели редизайн базы знаний
Главная цель базы знаний — дать клиентам возможность в любое удобное для них время самостоятельно найти ответы на большинство интересующих вопросов об услугах и биллинге. Что мы для этого сделали, рассказала Камилла Гарифуллина, старший технический писатель отдела знаний Selectel.
Три года назад мы впервые собрали все инструкции по использованию наших сервисов на одной платформе. Тогда внешний вид и техническая реализация базы знаний закрывали все потребности ее читателей.
Содержание
1. Задача с тремя переменными
2. “Лучшая база знаний позволяет без поиска найти, что тебе нужно”
2.1. [тех] реализация
2.2. Confluence мне друг, но Docs-as-Code удобнее
2.3. Визуальное решение
3. Резюме
В 2019 году мы заметили, что online-справка перестала отвечать требованиям наших клиентов из-за:
- слишком обширного меню навигации,
- неудобного поиска,
- устаревшего внешнего вида.
Мы решили провести тотальный редизайн, поменять концепцию и перезапустить базу, используя популярный сегодня принцип Docs-as-Code. Вот, как это было.
Задача с тремя переменными
Итак, время шло, наши продукты развивались, а база знаний все сильнее отставала от них. Найти нужные статьи становилось все сложнее. А когда статьи всё-таки находились, то многие из инструкций были слишком объемными и часто дублировались.
Мы проанализировали собственный опыт и изучили практики других участников рынка. Чаще всего встречались такие проблемы с документацией. *Нас они тоже не обошли стороной.
- Документация вообще отсутствует или никто не знает о ее существовании. Инструкция, которую нельзя найти, ничем не лучше инструкции, которой нет.
Наше решение:
— добавили ссылки на полезные статьи в нашей ежемесячной рассылке,
— включили переходы на продуктовых страницах сайта,
— наладили оповещение всех заинтересованных сотрудников компании через специальный канал в корпоративном мессенджере.
- #БазаЗнаний устаревает и вовремя не актуализируется. Процесс документирования не встроен в разработку продукта, документация делается по остаточному принципу.
Наше решение. Теперь менеджер по продукту в процессе работы над новой функциональностью также ставит задачу на ее документирование.
- Документация сложная и плохо организована, проще спросить у техподдержки, как решить возникший вопрос. Писать документацию ради документации бессмысленно, она должна быть легко доступна. Чем больше вариантов найти нужный документ, тем лучше.
Наше решение. Мы пересмотрели конструкцию разделов нашей базы знаний, в некоторых случаях универсальные шаблоны не работали, поэтому надо было активно взаимодействовать со всеми заинтересованными сторонами: менеджерами продукта, технической поддержкой или командой фронтенд-разработки.
“Лучшая база знаний позволяет без поиска найти, что тебе нужно”
Такую базу знаний мы и решили построить. Мы начали с того, что выделили основные типы пользователей — клиенты и сотрудники. При этом они будут иметь разные цели.
Цели БЗ для клиентов:
- для принятия решения о покупке,
- для самостоятельной настройки,
- для быстрого решения срочного вопроса.
Цели БЗ для сотрудников:
- для обучения/шпаргалки,
- для быстрого поиска необходимой клиенту инструкции.
В итоге, наш проект состоял из двух частей: технической стороны и визуального решения.
[тех] реализация
Первоначально база знаний Selectel была построена на основе объединения Confluence и генератора статических страниц.
Мы отказались от Confluence и перешли к принципу Documentation-as-Code.
Все исходные тексты для базы знаний мы верстаем в формате Markdown и храним в Git-репозитории.
#Markdown — упрощенный язык разметки. Используется для написания текста максимально удобного для правок и пригодного для преобразования в языки продвинутых публикаций, включая HTML.
Из хранилища с помощью генератора статических сайтов Hugo собирается сайт базы знаний. Сайт генерируется из файлов, содержащихся в master-ветке Git-репозитория. Обновить данные можно только через pull-request, это позволяет проверить все новые разделы документации перед тем, как они будут опубликованы в общем доступе. Такая система также облегчает подход к внесению правок — сотрудники компании всегда могут создать ветку и добавить в нее нужные изменения.
#Git-репозиторий — каталог файловой системы, в котором находятся файлы конфигурации хранилища и журналов. Файлы содержат операции (выполняемые над репозиторием), индекс (описывающий расположение файлов) и хранилище (содержащее собственно файлы).
Confluence мне друг, но Docs-as-Code удобнее
Нашу новую базу знаний мы устроили по принципу Documentation-as-Code. Этот подход подразумевает использование при написании документации того же инструментария, что и при создании кода: языков разметки текста, систем контроля версий, code review.
Основные преимущества Docs-as-Code в следующем.
- Коллаборация с разработчиками: многие из них предпочитают работать прямо в текстовом редакторе в формате Markdown.
- Обновление без предела: можно редактировать десятки страниц и вносить код в свой репозитарий, нет необходимости разворачивать что-то вручную.
- Тесная связь с участниками процесса: благодаря работе с контентом в одном и том же Git-репозитории.
- Гибкость и контроль по отношению к среде.
Визуальное решение
Мы пересмотрели навигацию и создали правила для формирования разделов базы знаний. Вместе с UX*-проектировщиками, в ведении которых опыт и впечатления пользователей от взаимодействия с опциями, подготовили информационную архитектуру. При этом помнили про основное требование к структуре — максимальная прозрачность. Читатель не должен думать: «А где можно найти эту статью?»
**UX или User eXperience**. Это опыт/впечатление, получаемые пользователем от работы с продуктом/услугой. Задача UX-проектировщика — создать логичный интерфейс и простой сценарий для использования продукта/услуги максимально удобным путем.
**UI или User Interface**. Это визуальный вид продукта. Задача UI-специалиста — сделать целостный, красивый и удобный интерфейс. Здесь важны такие характеристики: как цветовое решение, размер кнопок, читаемость текста.
Чтобы точнее понять, как лучше организовать и структурировать нашу базу знаний, изучили базы данных других участников рынка.
На основе изученных примеров мы выделили два основных подхода к внешнему виду документации, которые могут сработать:
- От интерфейса. Содержание дублирует разделы панели Selectel. Документация строится отдельно по услугам. Так было в предыдущей версии базы знаний.
- От задач. Названия статей и разделов строятся от задач пользователей.
В итоге мы применили комбинацию двух подходов.
Мы действуем по принципу “один продукт = один раздел БЗ”. При открытии вкладки “Серверы” теперь увидим следующее окно.
Здесь мы сразу даем определения сложных терминов и добавляем в быстрый доступ инструкции по всевозможным вопросам, начиная от регистрации в панели управления Selectel до работы с S3 API в Облачном хранилище.
Допустим, вы решили провести диагностику сервера. Идем по пути “Серверы” — “Инструкции” — “Как провести диагностику сервера”. Хлебные крошки покажут ваш путь поиска и дадут возможность вернуться на любой из предыдущих уровней. Решили познакомиться с бета-версией услуги Managed Kubernetes, но плохо разбираетесь в терминах? У нас есть глоссарий, где все подробно объяснено.
Резюме
В итоге вот, что изменилось.
- Появился рубрикатор по продуктам на главной странице. Можно сразу перейти в раздел о конкретном сервисе.
- Добавили быстрый поиск с подсказками по ключевым словам. А также теперь работают похожие запросы и опережающий поиск.
- Изменили поиск, он не уезжает под “шапку” сайта при скролле страницы, как это было раньше.
- Сделали поддержку разных разрешений экрана для комфортной работы. Сейчас удобно пользоваться базой знаний с мобильных устройств.
- Улучшили читаемость текста: шрифт стал крупнее, отступы более сбалансированы.
- Обновили заголовки — сделали их более понятными, ведущими к соответствующим инструкциям и разделам.
— У нас, когда долго бежишь, непременно попадаешь в другое место.
— Ну, а здесь, знаешь ли, приходится бежать со всех ног, чтобы только остаться на том же месте, а чтобы попасть в другое место, нужно бежать вдвое быстрее.
Если вы увидели, что еще мы можем изменить/дополнить в базе знаний или хотите поделиться с нами ссылками на другие удобные и классные справочники, пишите комментарии или присылайте письма на kb@selectel.ru.
Только Selectивный отбор. Не только Hardcore, но и Cloud.
Ваш Selectel
Понравился материал?
Подписывайтесь и следите за обновлениями:
Кстати, в Selectel много амбициозных вакансий!
Selectel в поисках UX-специалиста с опытом работы с веб-приложениями, с проектированием вайрфлоу, вайрфреймов и созданием прототипов. Вы будете решать сложные задачи, превращать интерфейсы в интуитивно понятные для использования для тысяч пользователей.
(Санкт-Петербург, гибкий график)
В команду Облачной платформы Selectel ждем драйвового специалиста, способного развивать с нами Serverless-направление. Вы будете формировать ценовую политику, бизнес-модель, работать над позиционированием и делать многое другое.
(Москва, гибкий график)
Разыскивается классный специалиста по UI в Selectel. Вы будете проектировать интерфейс веб-продуктов. А также анализировать результаты работы, выдвигать и проверять гипотезы, формировать/отслеживать метрики успешности и многое другое.
(Санкт-Петербург, полный день)
Если это статичные страницы, то как работает поиск?
Поиск в нашей БЗ реализован с помощью библиотеки Lunr.js.