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

Меня зовут Лена, я технический писатель в VAS Experts. В компании документация хранится в DokuWiki и размещена на двух площадках. В этой статье расскажем, почему для этой задачи мы выбрали именно платформу DokuWiki и какие собственные инструменты добавили поверх стандартных возможностей.

DokuWiki как единая база знаний

Основная задача нашей wiki — хранить знания о продуктах компании в одном месте. Здесь описываем изменения в новых версиях, новые функции, настройки, инструкции и справочную информацию. Документация постоянно обновляется вместе с продуктами, поэтому DokuWiki для нас — это не просто архив готовых документов, а рабочая база знаний.

Обновление документации проходит через обычный рабочий процесс. Информация о новых функциях и изменениях поступает от разработчиков и инженеров. Затем материалы готовят и отправляют на ревью специалистам, которые хорошо знают соответствующую функциональность. Подробнее о том, как устроен этот процесс, мы рассказывали в первой статье блога: «Как устроена wiki VAS Experts».

В результате пользователи получают единое место, где можно найти актуальную техническую информацию о продуктах.

Почему DokuWiki

При выборе платформы для технической документации для нас были важны несколько вещей: самостоятельное управление системой, удобная работа с контентом, сохранение истории изменений и адаптация wiki под собственные задачи. DokuWiki хорошо вписалась в эти требования.

DokuWiki — open-source wiki-движок для создания и ведения документации. Это достаточно простой и гибкий инструмент, который хорошо подходит для работы с технической документацией. 

Собственная инфраструктура

DokuWiki можно установить на собственную инфраструктуру. В нашем случае wiki работает на виртуальных машинах VAS Experts, поэтому мы сами управляем системой, данными и доступами. 

Это дает контроль над тем, где хранится документация и как организован доступ к ней.

Простота

Основная задача технической wiki — хранить и структурировать знания. В DokuWiki для этого есть все необходимые возможности: страницы, разделы, ссылки между материалами, изображения, таблицы, код и история изменений. 

При этом для работы с wiki не требуется сложная инфраструктура. Это особенно удобно для документации, которая постоянно развивается. В DokuWiki легко вносить изменения в контент, а при необходимости и расширять возможности самой wiki — например, устанавливать плагины или добавлять собственные доработки.

Возможность расширения

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

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

При этом сама DokuWiki остается основой системы, а дополнительные функции подключаются поверх нее.

История изменений

DokuWiki хранит историю изменений страниц. Можно посмотреть предыдущие версии материала, сравнить их между собой или восстановить предыдущий вариант страницы.

Для технической документации это полезно не только как механизм отката. История помогает понять, когда и почему изменился конкретный фрагмент материала.

Open-source

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

При этом open-source требует внимания к безопасности. Если использовать сторонние плагины, важно устанавливать их из надежных источников, следить за обновлениями и проверять информацию об известных уязвимостях. Устаревший плагин, как и любой другой сторонний компонент инфраструктуры, может стать потенциальным источником проблем.

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

Как мы используем DokuWiki

Наша техническая документация публикуется на двух платформах.

Основная площадка — wiki.vasexperts.ru. Здесь находится русскоязычная документация и создается ее английская версия. После подготовки англоязычная документация копируется на wiki.vasexperts.com с помощью скрипта синхронизации.

Упрощенно схема выглядит так:

wiki.vasexperts.ru остается основной площадкой, где ведется документация, а wiki.vasexperts.com содержит ее английскую версию.

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

Работа с переводами тоже частично автоматизирована. Для этого используем собственный плагин, который помогает переводить и отслеживать актуальность английской версии после изменений в русской статье.

При этом обе версии документации работают на одной платформе — DokuWiki.

Что мы добавили поверх DokuWiki

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

Сейчас у нас есть несколько самописных плагинов и скриптов. 

Они помогают:

• переводить документацию и контролировать актуальность переводов;

• синхронизировать отдельные разделы;

• работать с ИИ;

• собирать обратную связь;

• решать некоторые специфические задачи редакторов.

Есть и собственный шаблон интерфейса.

О наших плагинах и других доработках расскажем подробнее в следующей статье. За время работы их накопилось немало, и многие появились как ответ на конкретные задачи. Здесь же остановимся на DokuWiki как на основе всей этой системы. 

Что дает такой подход

Для нашей документации важны пять свойств DokuWiki.

1. Контроль — мы сами управляем инфраструктурой и данными.

2. Доступность — документация доступна пользователям через публичные wiki.

3. Простота — базовая платформа остается достаточно простой и не требует сложной инфраструктуры.

4. Гибкость — при необходимости ввести новую функциональность можно использовать готовый плагин или разработать собственное расширение.

5. Единая база знаний — основная документация хранится в одном месте, а английская версия автоматически переносится на второй сайт.

Для нас это сочетание оказалось удобным, поскольку базовая система DokuWiki остается достаточно простой, а регулировать сложность системы мы можем самостоятельно/специфические функции можно добавлять по мере необходимости.

Почему мы продолжаем использовать DokuWiki

DokuWiki это основа системы, вокруг которой постепенно сформировался собственный набор инструментов для работы с технической документацией.

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

За время работы вокруг стандартной DokuWiki появились инструменты для переводов, синхронизации, обратной связи и работы с ИИ. При этом базовая система остается простой и понятной.

Именно это сочетание для нас оказалось практичным: не искать платформу, которая сразу умеет всё, а взять достаточно простую основу и постепенно адаптировать ее под реальные задачи документации.