Как мы создаем документацию к проектам за 5 минут
Docs as Code — современный стандарт, к которому стремятся во многих компаниях. Но каждый раз настраивать сборку, дизайн, поиск, превью в MR и интеграции заново практически невозможно, особенно когда проектов много, а технических писателей мало.
Мы сделали AutoDoc — готовый шаблон на Docusaurus, который подключается добавлением одного пайплайна. Дальше можно писать Markdown и получать портал с поиском, диаграммами, OpenAPI-схемами и статистикой.
В cтатье разобрали, как это устроено и какие функции доступны из коробки.
AutoDoc — это zero-code-решение для Docs as Code. Оно помогает автоматически генерировать портал документации в любом репозитории простым добавлением пайплайна. В основе — Docusaurus с доступом ко всем его Markdown-возможностям.
Все, кто работает с документацией:
→ разработчики;
→ системные и бизнес-аналитики;
→ QA-инженеры;
→ технические писатели;
→ архитекторы.
Ничего не нужно настраивать: дизайн, структура, поиск, плагины для диаграмм — все уже готово. Нужно знание Markdown, базовые навыки работы с Git и умение коммитить файлы в IDE.
Мы собрали в шаблон все, что обычно приходится настраивать вручную:
→ встроенный поиск по документации;
→ превью в merge request — можно показать коллегам, как выглядят изменения до слияния веток;
→ обратную связь в формате виджета;
→ поддержку GitLab Pages из коробки;
→ локальную сборку для проверки;
→ возможность вести блог продукта рядом с документацией.
Просто выложить документацию мало — нужно понимать, читают ли ее. AutoDoc интегрирован с Grafana: для каждого портала собирается статистика посещений по всем страницам. Это помогает понять, какие разделы самые популярные, где у пользователей возникают вопросы и что действительно нужно командам, а что можно доработать или переписать.
AutoDoc поддерживает основные инструменты для диаграмм:
→ Mermaid — для блок-схем, графов, диаграмм последовательностей;
→ PlantUML — для UML-диаграмм;
→ Kroki — универсальный рендерер, который покрывает все: от BlockDiag и GraphViz до C4, D2 и Excalidraw;
→ LikeC4 — для интерактивных C4-диаграмм архитектуры.
Все диаграммы хранятся как текст в репозитории, их можно версионировать и смотреть изменения в MR.
У GitLab Pages есть проблема: нет общего поиска между разными документациями, как, например, в Wiki. Информация размазана по десяткам порталов, и найти что-то сквозное сложно.
Мы решили это через глобальный поиск: все публичные документации индексируются с помощью Search-as-a-Service, а с каждого autodocs можно перейти на страницу сквозного поиска, который позволяет найти контент среди всех документаций, использующих autodocs. Также там сейчас доступны поиск по репозиториям Gitlab и Wiki, а свой вопрос вместе с контекстом страницы можно отправить ИИ-ассистенту.