В этой серии статей расскажем, как устроена документация VAS Experts: из чего состоит база знаний, как в ней ориентироваться, кто и как ее создает, а также каким образом мы учитываем обратную связь пользователей, чтобы делать материалы понятнее и актуальнее.
Что такое Wiki VAS Experts
Wiki VAS Experts — это единая база знаний для наших клиентов и сотрудников компании. Ею пользуются инженеры внедрения, специалисты технической поддержки и другие команды. При создании документации мы стремимся сделать ее одинаково полезной для разных категорий пользователей — от тех, кто только начинает работать с продуктом, до опытных инженеров.
Рисунок 1 — Главная страница Wiki VAS Experts
Как ориентироваться
Документация сгруппирована по продуктам и тематическим разделам, а точкой входа в Wiki служит главная страница. На ней расположены три ключевых блока:
- Последние обновления — сведения о новых версиях продуктов и краткое описание изменений;
- Популярное — ссылки на материалы, которые чаще всего используются при работе с продуктами;
- Информация о продуктах — переход к документации по конкретным решениям VAS Experts. Для каждого продукта предусмотрен отдельный раздел с материалами, необходимыми для настройки и эксплуатации.
В зависимости от задачи в Wiki пользователь может найти разные типы материалов:
- Инструкции по установке и настройке — пошаговые руководства для развертывания и конфигурации компонентов;
- Описание функциональности — материалы о возможностях продуктов и принципах работы отдельных механизмов;
- Руководства пользователя и администратора — описание основных сценариев работы и управления системой;
- CLI-документация и описание параметров — информация о командах, настройках и конфигурационных параметрах;
- Release Notes — информация об изменениях в новых версиях, исправлениях и добавленных возможностях;
- FAQ и troubleshooting — ответы на частые вопросы и рекомендации по устранению типовых проблем;
- Примеры конфигураций и сценарии использования — практические материалы для настройки решений под конкретные задачи.
Чтобы упростить навигацию по большому объему информации, материалы организованы не только по типам документации, но и по продуктам, разделам и сценариям использования. В левой части интерфейса расположено дерево разделов — через него можно перейти к документации по продуктам, отдельным компонентам, разделам поддержки, лицензированию, спискам изменений и другим материалам.
Раздел «Начало работы» объединяет материалы, необходимые для подготовки к внедрению и первичной настройке СКАТ. Здесь пользователь может ознакомиться с назначением продукта, требованиями к оборудованию и рекомендациями по производительности, узнать об этапах тестирования и интеграции, а также изучить тестовые сценарии для проверки работоспособности системы.
Рисунок 2 — Меню
Кроме того, в разделе представлены инструкции по установке СКАТ с помощью скрипта, схемы подключения, информация о лицензировании и руководство по работе с личным кабинетом клиентов VAS Experts.
Далее в дереве документации расположены разделы, посвященные отдельным продуктам VAS Experts и компонентам СКАТ. Каждый раздел содержит материалы по настройке, эксплуатации и администрированию соответствующего решения.
Поиск информации в Wiki
Если пользователь не знает, в каком разделе находится нужная информация, можно воспользоваться поиском по всей базе знаний. Он позволяет находить материалы по названию, функциональности, компонентам продукта, параметрам конфигурации, командам, сообщениям об ошибках и ключевым терминам.
Кроме классического поиска, в Wiki реализован AI-поиск, который позволяет задавать вопросы в свободной форме. Пользователю не обязательно знать точное название статьи или параметра — система анализирует смысл запроса и подбирает релевантную информацию из базы знаний.
Рисунок 3 — Поисковая система
Рисунок 4 — AI-поиск
Почему Wiki не стоит на месте
За тем, что вы всегда находите актуальную информацию, стоит постоянная работа: Wiki VAS Experts обновляется вместе с продуктами, а материалы пишутся так, чтобы быть понятными профессиональной аудитории — сетевым инженерам, системным администраторам, техническим директорам операторов связи. Поэтому вместо объяснения базовых понятий мы делаем акцент на пошаговых инструкциях, примерах конфигураций и рекомендациях по эксплуатации.
Откуда берется новый материал
Создание документации начинается с появления потребности в новом материале или обновлении существующей информации. И самый частый повод для этого — релиз.
Для пользователя новая версия СКАТ — это список новых возможностей и исправлений. Для команды документации — начало новой задачи. Сначала нужно разобраться, какие изменения появились в каждом компоненте, понять, что важно для пользователя, а затем решить, достаточно ли обновить существующий материал или потребуется написать новую статью. Сам список изменений (changelog) не отвечает на вопрос, как пользоваться новой функциональностью, поэтому технический писатель подробно разбирает изменения вместе с разработчиками и инженерами внедрения.
При этом новые задачи появляются не только во время подготовки релизов. Иногда функциональность разрабатывается вне общего релизного цикла. В этом случае запрос на документацию приходит через Redmine или рабочие чаты и проходит тот же путь — от анализа изменений до подготовки и публикации материала.
Ещё одно постоянное направление работы — поддержка уже опубликованной документации. Мы актуализируем статьи после изменений в продукте, исправляем неточности, дополняем инструкции и отвечаем на вопросы, которые возникают у коллег и клиентов в процессе эксплуатации.
Независимо от того, что стало причиной обновления, каждый материал проходит техническое ревью. Специалисты проверяют корректность описания, полноту информации и соответствие документации реальному поведению продукта. Это позволяет публиковать материалы, которым можно доверять и которые действительно помогают в работе.
Как вы можете на это повлиять
Документация становится лучше, когда мы слышим тех, кто ею пользуется. На Wiki есть два способа поделиться мнением.
Самый быстрый — форма «Была ли полезна эта информация?» в конце каждой статьи. Достаточно одного клика, чтобы оценить материал, а если хочется сказать больше — можно оставить комментарий своими словами.
Рисунок 5 — Форма «Была ли полезна эта информация?»
Рисунок 6 — Форма «Была ли полезна эта информация?»
Если же вы хотите рассказать не про отдельную статью, а про Wiki в целом, обратите внимание на плашку с кнопкой «Сообщить нам» под левым меню — она под рукой практически на любой странице базы знаний.
Рисунок 7 — Обратная связь по кнопке «Сообщить нам»
Также найти ее можно в разделе на странице с результатами поиска:
Рисунок 8 — Обратная связь в разделе поиска
По кнопке открывается простая форма — заполнить ее займет пару минут. Мы будем рады, если вы напишете нам, когда:
- заметили ошибку или неточность в описании функциональности;
- не нашли нужную информацию в документации;
- увидели устаревший пример настройки;
- хотите, чтобы в статье было больше пояснений или примеров;
- столкнулись с неудобством в структуре или навигации;
- не смогли найти нужный раздел через поиск.
Каждое такое сообщение обязательно попадает в работу команды документирования. Именно так, шаг за шагом, вместе с вами мы делаем Wiki VAS Experts понятнее и удобнее.
Рисунок 9 — Обратная связь по кнопке «Сообщить нам»
