Из чего состоит наш промышленный конвейер документации для сложных продуктов

В компании «Юниверс Дата» мы разрабатываем комплексные системы управления данными. Четыре продукта, два из которых — флагманские, представляют собой многофункциональные платформы со сложными взаимосвязями между компонентами. Каждая функция может влиять на другую, порождая множество нюансов, исключений и технических примечаний. Объём и глубина контента, который необходимо описывать, огромны.

Продуктовая специфика диктует жёсткие требования к документации:

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

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

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

Движок генерации статичных сайтов

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

Архитектура конвейера: автоматизация как основа

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

1. Изоляция и переносимость: Движок Sphinx живёт на отдельном сервере приложений. Со временем мы вынесли его в кастомный Docker-контейнер, чтобы добиться воспроизводимости сборок. И мы строго контролируем обновления движка, обновляемся только раз в определенный период, как правило чтобы получить новые требуемые фичи или поддержку плагинов.
2. Отделение контента от логики: Исходный текст документации хранится в отдельном проекте GitLab. Каждая ветка соответствует версии конкретного продукта.
3. Мультисайт и переключатель: В результате сборки на сервере приложений создаётся статический сайт, объединяющий несколько инстансов (по продуктам и версиям). Между ними работает единый переключатель.
4. CI/CD как кровеносная система: Процесс управляется pipeline в GitLab:
• Автосборка при пуше в ветку.
• Автодеплой на тестовый стенд.
• Ручной запуск деплоя на продакшен (после ревью).
5. Выгрузка в Word — осознанный компромисс: Помимо HTML-сайта, конвейер автоматически генерирует документацию в формате Microsoft Word. Мы отказались от PDF в пользу DOCX по прагматичной причине: итоговые файлы часто требуют дополнительного редактирования (замена титульных страниц, кастомное оглавление, удаление разделов для конкретного заказчика).Поэтому выгоднее поправить Word-файлы и затем конвертировать их в PDF. Важный лайфхак: используйте файл-шаблон (.dotx). Хотя стилизация через шаблон имеет ограничения, корректно подготовленные образцы оформления таблиц, списков и кода позволяют сборщику применять ваши фирменные стили. Также учитывайте, что все оглавления в файле при генерации файлов не будут обновлены, и их требуется обновлять вручную.

Процессы: что важнее инструментов

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

• Управление контентом: Работа ведётся в IDE с поддержкой синтаксисов RST/MD, через Git, с код-ревью. Это обеспечивает контроль качества и истории изменений.
• Управление конфликтами: Для совместного редактирования мы выработали три принципа:
1. Чёткое разделение ответственности за модули документации между авторами.
2. Централизованное разрешение конфликтов — выделенный ответственный (техлид документации) проводит слияние веток и принимает спорные решения.
3. Ветвление в Git для параллельной работы над крупными обновлениями с последующим аккуратным мержем.
• Политика документирования и стайлгайд: Обязательный элемент внутренний стайлгайд. Он регламентирует тон, голос, структуру и оформление для каждого жанра документации (пошаговые инструкции, API справка, концептуальное руководство). Часть правил, например, проверку терминологии или сложности предложений, сегодня можно автоматизировать. Особенно, когда существуют такие инструменты как Cursor AI.
• Метаданные. Когда мы работали в Word, мы помечали каждое новое изменение в файле комментариями, где указывали ссылку на описываемую функцию или на баг. Это позволяло создавать уникальную память документации и быстро находить ответы для спорных тем в разработке. Но это было трудоемко и неудобно. При переходе на Docs as Code мы сохранили идею, но теперь метаданные сохраняются в виде имён коммитов и комментариев к коммитам.
• Документация по интеграции / SDK. Через время мы пришли к тому, чтобы предоставлять публичную документацию на определенный API-сервис. При выборе движка мы не думали об этом (не делайте так, изучайте требования к инструменту с запасом), но Sphinx приятно нас удивил и позволил легко поддержать интеграцию Swagger на сайте. На сегодняшний день мы встроили интерфейс Swagger напрямую, и встроили Javadoc и SDK UI через простые iframe теги. Схема не самая элегантная, но решает текущие задачи, и когда достигнет определенной зрелости будет улучшена.

Минусы Sphinx и границы подхода

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

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

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

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