В статье приводится практический опыт перехода от “офисных” документов к подходу Docs‑as‑Code на примере проекта ODS (Open Documentation Standard). Рассматриваются причины отказа от MS Word и выбор AsciiDoc, версионирование документации в Git, автоматизацию сборки PDF и публикацию документации на сайте, используя генератор статических сайтов – Antora.

Эта статья о проекте ODS (Open Documentation Standard) – открытом стандарте и инструментарии для автоматизации процессов создания и поддержки технической документации в ИТ и других проектах.
(Не связан с форматом OpenDocument Spreadsheet (.ods) или проектами Open Data.)

В открытом доступе находятся репозиторий и сайт ODS проекта.

Вечная боль технической документации

Документация живёт в MS Word и Excel, «шаблоны ГОСТ» лежат где‑то в сетевой папке, согласования идут в чате или почте, а изменения в файлах превращаются в бесконечные:

финал_финал_2_исправлено_после_замечаний.docx

С Word всё хорошо, пока документация не развивается и не требует регулярной актуализации. Но когда проекты растут и появляются всё новые версии, возникают типичные проблемы:

Версионирование – сложно поддерживать версии документации.
Проверка и комментарии – сравнение .docx плохо похоже на ревью кода; комментарии живут отдельно от истории изменений.
Повторное использование – «вставить в 17 документов один и тот же фрагмент» почти всегда заканчивается рассинхроном.
Стандартизация – тяжело гарантировать, что все документы собраны одинаково и строго по шаблону.
Сборка комплектов – ГОСТ‑комплекты, ведомости и спецификации обычно собираются вручную.

Требования к документированию

Мы хотели, чтобы документация разрабатывалась как код:

хранилась в одном месте и версионировалась;
прозрачно проходила ревью;
имела единую структуру и возможность переиспользовать фрагменты текста;
могла синхронизироваться с разработкой – например, отражать актуальное состояние БД и API;
автоматически собиралась в комплект с едиными стандартами оформления.

Выбор пал на AsciiDoc

Для большого массива технической документации нам было необходимо иметь следующий функционал:

include – сборка документа из блоков;
атрибуты – объявление переменных и констант с повторным использованием;
сложные таблицы – заголовки, объединение и выравнивание ячеек;
ссылки между разделами и файлами с контролируемыми наименованиями;
диаграммы – возможность встраивать UML и BPMN без скриншотов;
кастомизация стилей оформления;
кросс‑компиляция в HTML и PDF.

��ткрытая экосистема Asciidoctor позволяет максимально реализовать эти требования. Язык разметки AsciiDoc предоставляет мощные средства форматирования контента, а инструменты с открытым исходным кодом дают возможность гибко кастомизировать сборку документации под разные требования.

Базовые «кирпичики» AsciiDoc

В AsciiDoc атрибуты задаются так:

:year: 2025  
:contract-date: от 01 января {year} года  
:contract-number: № 12345-ИО  
:director: Иванов А.А.

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

Например, атрибуты можно вынести в отдельный файл contract.adoc и подключить его:

include::contract.adoc[]
// tag::intro[]
В соответствии с Договором {contract-date} {contract-number} …  
// end::intro[]

Использование в документе:

== Введение  

include::xxx.adoc[tag=intro]

Также можно использовать целые предложения в качестве атрибутов:

:intro: В соответствии с Договором {contract-date} {contract-number} …

== Введение  
{intro}.

Подобные конструкции могут применяться в нескольких документах проекта.

Версионирование с Git

По завершении формирования документов можно поставить в репозитории Git соответствующий тег, например v1.1.0_latest_2025, или оставить документацию на отдельной ветке doc_latest_2025.

Далее можно начать формировать проект 2026 года, создав новую ветку и заменив соответствующие атрибуты:

:year: 2026  
:contract-date: от 10 января {year} года  
:contract-number: № 6789-ИО  
:director: Петров А.А.

При этом неизменным останется атрибут:

:intro: В соответствии с Договором {contract-date} {contract-number} …

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

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

Проект ODS (Open Documentation Standard)

ODS – это не «ещё один стандарт документации». Это попытка собрать воедино подход Docs‑as‑Code для документирования проектов.

Основные требования

Проект должен был соответствовать следующим требованиям:

единый формат исходного кода документации;
автоматизация сборки документов и комплектов;
генерация частей документации из БД и OpenAPI;
использование LLM‑моделей для рутинных задач;
публикация документации на сайте с печатными формами.

Как устроен репозиторий

Репозиторий содержит следующие основные папки проекта:

components/ – компоненты документации (по смыслу: сервисы, системы, гайды);
- components/<name>/modules/<module>/pages – страницы (Antora формирует HTML из pages);
- components/<name>/modules/<module>/partials – переиспользуемые фрагменты текста, подключаемые через include:: (из partials HTML не формируется);
tools/ – Ruby‑инструменты автоматизации и конфигурации;
templates/ – шаблоны документации;
antora-playbook.yml – файл конфигурации Antora.

Такая структура позволяет реализовать модульность документации и параллельно вести несколько проектов или систем в одном репозитории.

Автоматизация в ODS

Теперь – про то, что обычно «ломает» мечту о Docs‑as‑Code: печать по ГОСТ, автогенерация из БД и API, сборка всего комплекта документов.

Главный оркестратор – скрипт tools/start.rb. Он проходит по компонентам из файла конфигурации и, в зависимости от флагов, выполняет:

Конвертацию BPMN (Node + Puppeteer).
Конвертацию Draw.io (Node).
Генерацию AsciiDoc из OpenAPI / Swagger.
Генерацию AsciiDoc и диаграмм из PostgreSQL, преобразование и перевод атрибутов.
Генерацию служебных списков, ссылок и таблиц.
Генерацию листов утверждения, спецификаций и ведомостей.
Генерацию PDF (Asciidoctor PDF + кастомные конвертеры).

Запуск командой:

ruby tools/start.rb

Запускается скрипт start.rb и выполняется сборка ��роекта согласно сценарию, заданному в файле config.yml. В результате сборки проекта появляются артефакты, готовые к печати и/или публикации на сайте.

PDF «по ГОСТ» или по шаблонам

Инструменты Asciidoctor PDF предоставляют широкие возможности настройки тем оформления документов, но ГОСТ подобное оформление часто упирается в проблемы:

рамки и штампы;
нестандартные титульные страницы;
особые правила нумерации списков и колонтитулов.

Поэтому в ODS генерация PDF построена так:

Asciidoctor PDF делает базовую вёрстку контента;
кастомные Ruby‑конвертеры оформляют рамки, титульные страницы, листы утверждения и стилизуют списки.

Документация из внешних источников

ODS поддерживает генерацию документации из:

PostgreSQL – таблицы, поля, комментарии, ERD‑диаграммы;
OpenAPI / Swagger – структура API, методы, параметры и ответы.

Для перевода названий таблиц и полей БД используется словарь терминов и локальные LLM‑модели через Ollama. Словарь имеет приоритет при переводе, а LLM используется пакетно, что позволяет сохранить точность и обеспечить приемлемую скорость. Словарь можно править вручную, а при следующем переводе ваши данные будут использованы скриптом напрямую. При появлении новых данных, они транслируются в tools/log/database_translations_log.txt, что удобно для контроля перевода последних изменений.

Сайт документации: Antora

Для публикации документации используется генератор статических сайтов Antora.

Он обеспечивает:

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

Автоматически сформированные на предыдущем этапе списки используются Antora для формирования ссылок в навигации и к сформированным PDF‑документам.

Antora в ODS отвечает только за сборку сайта. Файл конфигурации antora-playbook.yml используется для установки атрибутов-ключей для условных операторов, которые разделяют сборку PDF и сборку сайта.

Итог

ODS – это попытка сделать техническую документацию:

воспроизводимой;
версионируемой;
связанной с реальными источниками данных;
проверяемой и удобной для ревью (как код);
автоматически собираемой в готовый комплект.

На практике это помогает держать документацию в актуальном состоянии, ускоряет онбординг и упрощает масштабирование проекта без превращения документации в “кладбище файлов”.

Если вы хотите повторить этот подход у себя, практический совет прост: начните с AsciiDoc, подключите Git и научитесь собирать PDF. Всё остальное можно подключать постепенно, когда появится стабильный и понятный «скелет» документации.

Посмотреть реализацию ODS можно в репозитории и на сайте документации:

https://gitlab.com/vvvnik/ods-project
https://vvvnik.gitlab.io/ods-project/project-guide/1/index.html

Docs-as-Code на практике: автоматизация сборки документации в проекте ODS