IT-инфраструктура для бизнеса и творчества
Разработка
Selectel

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

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

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

Содержание

1. Задача с тремя переменными

2. “Лучшая база знаний позволяет без поиска найти, что тебе нужно”

2.1. [тех] реализация

2.2. Confluence мне друг, но Docs-as-Code удобнее

2.3. Визуальное решение

3. Резюме

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

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

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

Задача с тремя переменными

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

Внешний вид базы знаний до редизайна

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

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

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

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

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

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

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

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

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

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

“Лучшая база знаний позволяет без поиска найти, что тебе нужно”

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

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

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

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

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

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

Топ сервисов для ведения баз знаний:

MediaWiki, DokuWiki, Confluence, DropBox, Evernote, ntile.app, sphinx, Wikiworks.

[тех] реализация

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

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

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

#Markdown — упрощенный язык разметки. Используется для написания текста максимально удобного для правок и пригодного для преобразования в языки продвинутых публикаций, включая HTML.

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

#Git-репозиторий — каталог файловой системы, в котором находятся файлы конфигурации хранилища и журналов. Файлы содержат операции (выполняемые над репозиторием), индекс (описывающий расположение файлов) и хранилище (содержащее собственно файлы).

Confluence мне друг, но Docs-as-Code удобнее

Принцип Docs-as-Code Источник: starkovden.github

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

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

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

Визуальное решение

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

**UX или User eXperience**. Это опыт/впечатление, получаемые пользователем от работы с продуктом/услугой. Задача UX-проектировщика — создать логичный интерфейс и простой сценарий для использования продукта/услуги максимально удобным путем.

**UI или User Interface**. Это визуальный вид продукта. Задача UI-специалиста — сделать целостный, красивый и удобный интерфейс. Здесь важны такие характеристики: как цветовое решение, размер кнопок, читаемость текста.

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

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

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

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

Внешний вид обновленной базы знаний

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

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

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

Резюме

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

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

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

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

Л. Кэрролл "Алиса в Зазеркалье"

Если вы увидели, что еще мы можем изменить/дополнить в базе знаний или хотите поделиться с нами ссылками на другие удобные и классные справочники, пишите комментарии или присылайте письма на kb@selectel.ru.

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

Ваш Selectel

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

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

Кстати, в Selectel много амбициозных вакансий!

UX проектировщик

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

(Санкт-Петербург, гибкий график)

Product Manager

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

(Москва, гибкий график)

Проектировщик интерфейсов

Разыскивается классный специалиста по UI в Selectel. Вы будете проектировать интерфейс веб-продуктов. А также анализировать результаты работы, выдвигать и проверять гипотезы, формировать/отслеживать метрики успешности и многое другое.

(Санкт-Петербург, полный день)

(function () { let cdnUrl = `https://specialsf378ef5-a.akamaihd.net/SelectelBranding/images/` let previousArticleNumber = null let currentArticleNumber = 0 let platform = 'Desktop' let articles = [ { name: 'camera', url: `${cdnUrl}CameraCat`, text: 'умную камеру для\u00A0наблюдения за\u00A0котиками', link: 'https://vc.ru/selectel/306690', num: 3 }, { name: 'chill', url: `${cdnUrl}ChillCat`, text: 'трекер, который подскажет, когда пора отдохнуть', link: 'https://vc.ru/promo/288561-eye-tracker', num: 1 }, { name: 'cloud', url: `${cdnUrl}CloudCat`, text: 'котика: даёшь ему «пять», а\u00A0он делает бэкап в облако', link: 'https://vc.ru/dev/294799-maneki-neko', num: 2 } ] let buttonCycle = document.querySelector('.button--cycle') let buttonChoose = document.querySelector('.button--choose') let buttonMobile = document.querySelector('.button--mobile') let textField = document.querySelector('.selectel-footer-subtitle') let imageAgent = document.querySelector('.image--agent') let banner = document.querySelector('.selectel-footer') buttonCycle.addEventListener('click', cycleClick) buttonChoose.addEventListener('click', () => sendEvent(`Promo ${articles[currentArticleNumber].num} Left`, 'Click')) buttonMobile.addEventListener('click', () => sendEvent(`Promo ${articles[currentArticleNumber].num} Left`, 'Click')) let media = window.matchMedia("(max-width: 570px)") media.addEventListener('change', matchMedia) function matchMedia() { if (media.matches) { platform = 'Mobile' } else { platform = 'Desktop' } update() } matchMedia() function cycleClick(event) { sendEvent(`Promo ${articles[currentArticleNumber].num} Right`, 'Click') if (event) { event.preventDefault() event.stopPropagation() } window.open('https://vc.ru/tag/selectelDIY', '_blank') //cycle(event) } function cycle(event) { // incrementArticleNumber() textField.innerHTML = generatedText() imageAgent.src = articles[currentArticleNumber].url + platform + '.svg?3' imageAgent.setAttribute("class", "") imageAgent.classList.add('image--agent', articles[currentArticleNumber].name) banner.href = articles[currentArticleNumber].link } function update() { banner.href = articles[currentArticleNumber].link imageAgent.src = articles[currentArticleNumber].url + platform + '.svg' textField.innerHTML = generatedText() } function incrementArticleNumber() { previousArticleNumber = currentArticleNumber if (currentArticleNumber >= articles.length - 1) { currentArticleNumber = 0 } else { currentArticleNumber++ } } const sendEvent = (label, action = 'Click') => { const value = `SelectelDIY — loc: Footer — ${label} — ${action}`; if (window.dataLayer !== undefined) { window.dataLayer.push({ event: 'data_event', data_description: value, }); } }; function generatedText() { let defaultText if (platform === 'Desktop') { defaultText = `Мы тут собрали %text%. Хотите научим?` } else { defaultText = `Мы тут собрали %text%.` } return defaultText.replace('%text%', articles[currentArticleNumber].text) } function getRandom(min, max) { min = Math.ceil(min) max = Math.floor(max) return Math.floor(Math.random() * (max - min + 1)) + min } (function create() { currentArticleNumber = getRandom(0, articles.length - 1) cycle() let page = document.querySelector('.page--entry') if (page) { function insertAfter() { let parents = page.querySelectorAll('[data-id="7"]') let referenceNode = parents[0] referenceNode.parentNode.insertBefore(banner, referenceNode.nextSibling); loaded() } setTimeout(() => insertAfter(), 0) } }()) function loaded() { banner.classList.add('loaded') } loadImages([ `${cdnUrl}CameraCatDesktop.svg`, `${cdnUrl}ChillCatDesktop.svg`, `${cdnUrl}CloudCatDesktop.svg`, `${cdnUrl}CameraCatMobile.svg`, `${cdnUrl}ChillCatMobile.svg`, `${cdnUrl}CloudCatMobile.svg?3`, ]) function loadImages(urls) { return Promise.all(urls.map(function (url) { return new Promise(function (resolve) { var img = document.createElement('img'); img.onload = resolve; img.onerror = resolve; img.src = url; }); })); } }())
0
2 комментария
Популярные
По порядку

Если это статичные страницы, то как работает поиск?

1

Поиск в нашей БЗ реализован с помощью библиотеки Lunr.js.

2
Читать все 2 комментария
Наследник Рокфеллера, сын Софи Лорен, боксёр и продюсер: история француза, обманувшего Рурка, Ван Дамма и других звёзд Статьи редакции

СМИ прозвали Кристофера Роканкура звёздным мошенником: его жертвами были голливудские знаменитости и американские предприниматели. Точная сумма ущерба от действий француза неизвестна, но сам он утверждает, что за свою жизнь «заработал» $40 млн.

Кристофер Роканкур и Наоми Кэмпбелл francetvinfo
Бизнес — как ребенок: как мамы совмещают свое дело с заботой о детях

Как совмещать бизнес и семью? Ко Дню матери своими историями поделились бизнесвумен, которые работают c ЮKassa и занимаются детьми. Читайте, как им удается сохранять жизненный баланс и добиваться успеха.

Хочу кухню как у подруги: зачем в Циан сделали поиск квартир по фото

Рассказывает Юлия Зыкова, руководитель команды «Аудитория» в Циан.

Возник по просьбе бразильских банкиров и стал любимым напитком солдат во время Второй мировой: история Nescafe Статьи редакции

В 2021 году Nescafe — крупнейшее подразделение Nestle и бренд, который оценивается больше чем в $20 млрд. По собственным данным компании, в мире каждую секунду выпивают более 5000 чашек напитка.

Дегустация Nescafe National Museum
Бот, который сделает маму счастливее

Kind Bot напечатает и отправит по почте фото вашей маме. В 2 клика.

Из науки в IT: как создать свой стартап и стать преподавателем

Как перейти в IT из другой сферы? Как разработать курс, которому нет аналогов? Как студенту получить максимум пользы от занятий? Рассказывает преподаватель OTUS Сергей Окатов, руководитель курсов «Kotlin Backend Developer» и «Kotlin Developer. Basic».

Завод по производству идей. Как работают акселераторы, зачем они нужны стартапам и куда идти с идеей прямо сейчас

По данным Startup Genome, 9 из 10 стартапов терпят неудачу. Возможных причин «смерти» много: недостаточно протестированная гипотеза, неподтвержденная юнит-экономика, неверная стратегия или просто неудача в подходе к продажам.

Английский язык. Как это надо делать, если вернуть 2 года назад

Всегда считал себя неспособным к языкам, школу закончил, мягко говоря, с 0 знанием Английского языка. Как ,наверно, 95% населения нашей страны.

Как у меня украли 600 тысяч с карты, а Тинькофф нарушает федеральный закон

Спойлер: я НЕ вводил никуда код, НЕ переходил по ссылкам и НЕ сообщал данные карты.

Я всегда считал себя финансово грамотным человеком, сам когда-то работал в банке, соблюдал цифровую гигиену, держал деньги на нескольких счетах, не привязывал основную карту в непонятных сервисах, в 90% оплат пользовался Google Pay. Когда родственники присылали…

Как я заработал свой первый миллион просмотров на лонгридах

Мой опыт ведения текстового блога на «Виси», «Пикабу», «Хабре», Дзене и еще пачке площадок. Сколько потратил на них сил и какую отдачу в итоге получил.

Потратили $1 млн на клинику для профилактики здоровья зубов в Москве — и через десять месяцев закрыли проект

История о неудачном запуске монопродукта в стоматологии — его пришлось переформатировать.

Та самая клиника
null