Сравнение инструментов Docs as Code

Документация как код — это не просто модный термин. Это смена парадигмы: документация живет рядом с кодом, обновляется в том же пайплайне, проходит ревью в pull request и деплоится автоматически. Если вы слышали про Everything as Code — Docs as Code это его конкретная реализация для технических писателей и разработчиков.

В этой статье мы разберем четыре инструмента — Gramax, Docusaurus, MkDocs и GitBook по трем критериям, которые реально влияют на жизнь команды: гибкость, скорость настройки и удобство работы.

Что такое Docs as Code и зачем это вообще нужно

Классическая документация живет в Confluence, Notion или Word. Редактируют ее вручную, версионирование — в лучшем случае история правок. Когда разработчик меняет поведение API, документация обновляется позже, если вообще обновляется.

Docs as Code решает эту проблему структурно:

  • Документация хранится в Git вместе с кодом (или в отдельном репозитории, но по тем же правилам).

  • Изменения проходят через pull request — можно делать ревью, оставлять комментарии, требовать апрув.

  • CI/CD автоматически публикует обновления при мерже.

  • Контент в Markdown или MDX — читается без инструментов, диффится как код.

Это часть более широкого тренда Everything as Code, где инфраструктура, конфигурация, политики безопасности и теперь документация управляются одними и теми же инструментами — Git, YAML, CI/CD пайплайны.

Инструменты Docs as Code: кто есть кто

Прежде чем сравнивать, давайте зафиксируем, о чем вообще речь.

  • Docusaurus — опенсорсный генератор статических сайтов от Meta. Построен на React, поддерживает MDX (Markdown + JSX), имеет огромную экосистему плагинов.

  • MkDocs — Python-инструмент с простым YAML-конфигом. Легкий, быстрый, с популярной темой Material for MkDocs. Хорош для небольших и средних проектов.

  • GitBook — облачная платформа с Git-синхронизацией. Есть визуальный редактор, красивый дефолтный дизайн. Платный для большинства сценариев.

  • Gramax — российский инструмент для Docs as Code, ориентированный на корпоративные команды. Работает только локально. Имеет WYSIWYG-редактор поверх Git + Markdown, что делает его доступным не только для разработчиков.

Гибкость: насколько инструмент подстраивается под вас, а не вы под него

Docusaurus

Очень гибкий — если вы готовы писать на React. MDX позволяет встраивать интерактивные элементы прямо в документацию — диаграммы, live-примеры кода, кастомные блоки.

Обратная сторона: гибкость требует ресурсов. Чтобы добавить нестандартный блок или поменять структуру навигации, нужен фронтенд-разработчик или технический писатель с навыками React.

MkDocs

Гибкость ограничена Python-экосистемой и плагинами. Тема Material for MkDocs покрывает большинство потребностей из коробки — адаптивность, поиск, темная тема, мультиязычность. Но если нужно что-то нестандартное, придется писать собственный плагин или шаблон на Jinja2.

GitBook

Гибкость сознательно ограничена: платформа делает ставку на консистентный внешний вид. Кастомизация — в основном цвета, логотип и домен. Если нужна нестандартная структура страниц или кастомные компоненты — GitBook не для вас.

Gramax

Gramax дает гибкость там, где она нужна большинству команд, без необходимости лезть в код для стандартных сценариев. Структура документации, навигация, версионирование разделов — все настраивается через интерфейс. Стили, лого, шрифты — через CSS.

Скорость настройки: от нуля до работающей документации

Docusaurus

npx create-docusaurus@latest my-website classic
cd my-website
npm start

Три команды — и у вас есть работающий сайт. Это быстро. Но дальше начинается. Настройка навигации в docusaurus.config.js не очевидна. Sidebars.js требует понимания структуры. Деплой в CI нужно настраивать вручную. Если документация большая — работы на неделю-две.

MkDocs

pip install mkdocs-material
mkdocs new my-project
mkdocs serve

Еще быстрее для простых случаев: mkdocs.yml читается как человеческий текст. Структура навигации прозрачна. Для стандартного сценария — все настраивается за несколько часов.

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

GitBook

Самый быстрый старт — создал аккаунт, подключил репозиторий, нажал синхронизировать. Для команды без DevOps-экспертизы это критически важно: ничего не надо деплоить, сертификаты настраиваются автоматически, CDN включен. Цена быстроты — зависимость от вендора и платная подписка для большинства реальных кейсов.

Gramax

Gramax сделал ставку именно на скорость онбординга — причем не только технической части, но и для нетехнических авторов. Чтобы начать писать — один клик на сайте. Репозиторий подключается через интерфейс, без ручного редактирования конфига. Опубликовать в облако Gramax — за несколько кликов. На свой сервер или хостинг — за пару часов с помощью CLI или Docker.

Важный момент: в Gramax не нужно объяснять технической команде, как работает Git, чтобы технические писатели могли делать коммиты. WYSIWYG-редактор скрывает Git-операции за привычным интерфейсом — кнопка «Опубликовать» делает коммит и пуш.

Удобство работы: ежедневный опыт авторов

Это, пожалуй, самый важный критерий — потому что документацию пишут каждый день. И именно здесь инструменты разошлись сильнее всего.

Docusaurus

Для разработчика с настроенным VS Code и prettier — отличный опыт. Пишешь в редакторе, видишь превью в браузере, коммитишь, CI деплоит.

Для технического писателя без опыта Git — это квест. Создать файл в правильной директории, добавить frontmatter с правильными полями, добавить в sidebar, сделать коммит с правильным именем ветки — каждый шаг требует понимания контекста. Ошибка в YAML ломает сборку.

MkDocs

Чуть лучше — структура проще, конфиг понятнее. Но базовый опыт такой же: текстовый редактор + Git. Для опытных технических писателей, которые дружат с Markdown и консолью — вполне комфортно. Для остальных — порог входа есть.

GitBook

Максимально прост и доступен для всех. Редактор — Notion-подобный блоковый интерфейс с drag-and-drop. Версионирование скрыто под понятными концепциями «черновик» и «опубликованная версия». Ограничение — в коллаборации. Для большой команды нужен платный тариф.

Gramax

Gраmax строится на идее, что редактор документации должен работать как Notion, но под капотом хранить Git + Markdown. Авторы видят визуальный редактор — заголовки, таблицы, вставки кода с подсветкой синтаксиса .

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

Функционал для командной работы включает ревью прямо в интерфейсе, комментарии к конкретным абзацам и статусы публикации. Для технических писателей, которые привыкли согласовывать изменения в Google Docs, переход ощущается органично.

Кому что подойдет

  • Выбирайте Docusaurus, если у вас опенсорс-проект с активным сообществом, React-разработчики готовы поддерживать документацию.

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

  • Выбирайте GitBook, если нет DevOps-ресурса, документация публичная, а команда не готова разбираться с деплоем и инфраструктурой. Готовьтесь платить и принять ограничения.

  • Выбирайте Gramax, если у вас большая команда, где разработчики и нетехнические авторы работают вместе. Если нужен self-hosted с контролем над данными. Если хотите Docs as Code без необходимости убеждать каждого технического писателя освоить Git.

Итог

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

Инструменты для разработчиков (Docusaurus, MkDocs) дают максимум контроля, но требуют технической зрелости команды. Инструменты с редакторами (GitBook, Gramax) снижают порог входа — Gramax при этом не жертвует ни опенсорсом, ни self-hosted, ни совместимостью с Git-воркфлоу разработчиков.

Everything as Code работает только тогда, когда «все» действительно включает документацию — а не только ту ее часть, которую успевают обновлять разработчики в свободное время.