В статье приводится практический опыт перехода от “офисных” документов к подходу 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. Он проходит по компонентам из файла конфигурации и, в зависимости от флагов, выполняет:

  1. Конвертацию BPMN (Node + Puppeteer).

  2. Конвертацию Draw.io (Node).

  3. Генерацию AsciiDoc из OpenAPI / Swagger.

  4. Генерацию AsciiDoc и диаграмм из PostgreSQL, преобразование и перевод атрибутов.

  5. Генерацию служебных списков, ссылок и таблиц.

  6. Генерацию листов утверждения, спецификаций и ведомостей.

  7. Генерацию 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 можно в репозитории и на сайте документации: