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

Наш путь начался с классических файлов Microsoft Word. Однако по мере роста зрелости продуктов и усложнения их архитектуры этот подход стал тормозом. Управление версиями, согласованность правок, слияние изменений от разных авторов превратились в неподъёмную рутину. Мы достигли точки, где философия Docs as Code стала не модным трендом, а единственно верным инженерным решением для управления документацией.

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

Эта статья не про то, как мы выбирали движок. Поэтому, опуская этап анализа, мы остановились на Sphinx, генераторе статических сайтов. Нам было важно: экосистема плагинов, развитый синтаксис (reStructuredText) и, что ключевое, нативная поддержка управления как версиями продуктов, так и версиями релизов внутри одного продукта. Sphinx предоставил нам все, что было необходимо.

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

1. Изоляция и переносимость: Движок Sphinx живёт на отдельном сервере приложений. Со временем мы вынесли его в кастомный Docker-контейнер, чтобы добиться воспроизводимости сборок. И мы строго контролируем обновления движка, обновляемся только раз в определенный период, как правило чтобы получить новые требуемые фичи или поддержку плагинов.
2. Отделение контента от логики: Исходный текст документации хранится в отдельном проекте GitLab. Каждая ветка соответствует версии конкретного продукта.
3. Мультисайт и переключатель: В результате сборки на сервере приложений создаётся статический сайт, объединяющий несколько инстансов (по продуктам и версиям). Между ними работает единый переключатель.
4. CI/CD как кровеносная система: Процесс управляется pipeline в GitLab:

• Автосборка при пуше в ветку.
• Автодеплой на тестовый стенд.
• Ручной запуск деплоя на продакшен (после ревью).

Инструменты — лишь половина успеха. Вторая половина — выстроенные процессы.

• Управление контентом: Работа ведётся в IDE с поддержкой синтаксисов RST/MD, через Git, с код-ревью. Это обеспечивает контроль качества и истории изменений.
• Управление конфликтами: Для совместного редактирования мы выработали три принципа:

1. Чёткое разделение ответственности за модули документации между авторами.
2. Централизованное разрешение конфликтов — выделенный ответственный (техлид документации) проводит слияние веток и принимает спорные решения.
3. Ветвление в Git для параллельной работы над крупными обновлениями с последующим аккуратным мержем.

Sphinx не панацея, и его недостатки важно признать.

• Необходимость пересборки. Любое изменение, даже опечатка, требует запуска процесса сборки. Это занимает время и исключает возможность «редактирования на лету».
• Отсутствие WYSIWYG-редактора. Невозможно просто выделить текст и нажать кнопку для форматирования. Это требует от авторов знания RST/MD и работы в IDE, что создаёт высокий порог входа.
• Барьер для нетехнических авторов. Подход неудобен для массового привлечения авторов (например, консультантов или специалистов поддержки). Им требуется более простая, вики-подобная система.

Мы не стремились создать идеальную систему документирования. Мы создали систему, которая выдерживает сложность продуктов и остаётся управляемой по мере роста компании. Само сочетание Sphinx, Гит, Докера и автоматизированной сборки не является главной ценностью. Главную ценность создают согласованные правила и дисциплина команды.

Если вы только начинаете переход на Docs as Code, то в первую очередь обратите внимание на процесс, который хотите построить. Продумайте правила и кейсы использования. Затем подберите инструмент, который кажется самым удобным, и соберите MVP. В выборе есть один неочевидный критерий: язык, на котором написан генератор сайтов. Если вы выберете инструмент, созданный, к примеру, на PHP, а в компании никто языка не знает, это может быть проблемой для глубоких кастомизаций.