В мире разработки мы постоянно сталкиваемся с технической документацией — она повсюду, от спецификаций API до архитектурных решений. И мы хотим, чтобы документация была структурированной, актуальной и удобной… но в реальности чаще имеем дело с хаотичным набором разрозненных материалов, которые теряются между Confluence, почтой и Google Docs, стремительно устаревают и выглядят небрежно, с «плывущими» таблицами и запутанной структурой. Представили этот беспорядок?

Хорошая новость: есть способ автоматизировать и стандартизировать документацию, сделав её такой же управляемой, как код — через модель docs as code.

В статье вместе вспомним базовые принципы этого подхода, расскажем про наш опыт документирования и поделимся репозиторием с готовым шаблоном LaTeX для максимально быстрого старта без установки зависимостей!

База

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

В идеале, при работе с документацией мы хотим:

• Избавиться от рутины: никакого выравнивания таблиц вручную и пр.

• Сэкономить время: автосборка документа с оглавлением, ссылками, внутренней нумерацией, импортированной графикой.

• Получить «живую» документацию: версионирование и ревью, как в разработке.

Как этого достичь? Один из вариантов — через подход Docs as Code + LaTeX + контейнеризация.

Мы пришли к этому не сразу и не напрямую. На одном из наших проектов было требование оформить документацию именно в LaTeX, и свои первые результаты мы сохраняли в репозитории для удобного совместного доступа. Получилось, что мы интуитивно применяли концепцию docs as code, тогда еще явно не зная о ней. А по мере написания документации мы всё глубже погружались в LaTeX (нам зашло).

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

Docs as Code — почему это работает?

Docs as Code (документация как код) — это подход, при котором документация создается и поддерживается точно так же, как программный код. Вместо громоздких WYSIWYG-редакторов (вроде Word или Confluence) — чистый текст с разметкой, Git, ревью и автоматическая сборка.

Ключевые принципы docs as code:

• Текст вместо WYSIWYG. Только чистый текст с тегами разметки, без редакторов. И это не откат в 80е, когда еще не было текстовых редакторов с UI, а как раз та текстовая атмосфера, в которой находятся разработчики (можно даже не выходить из привычной IDE). Так получается сосредоточиться на смысле текста, а не на его оформлении.

• Git как единый источник правды. Исходные тексты документации лежат в системе управления версиями Git. Тут мы получаем все преимущества, как и с исходным кодом: создание фича веток, обновление документации через ревью (MR/PR), продвинутое версионирование, история изменений, возможность отката.

• Автоматическая сборка. Исходные файлы (*.md, *.tex) превращаются в нужный формат (PDF, HTML и др.) на этапе CI/CD. Например, Push в main → GitHub Actions собирает PDF → публикует его в артефактах.

Как результат — документы, которые живут вместе с проектом, а не пылятся на виртуальной полке. Docs as code — реальная альтернатива wiki-системам.

Подробнее про подход docs as code можно почитать тут и тут.

Язык разметки (LaTeX)

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

Существует ряд легковесных языков разметки. Самыми популярными являются Markdown и reStructuredText. И они отлично подойдут для простых документов. Однако, если требуется инструмент для сложных, структурированных документов с формулами, диаграммами, перекрестными ссылками и автоматическим оглавлением, то стоит смотреть в сторону TeX(LaTeX).

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

LaTeX можно использовать как программируемый инструмент для вёрстки. Условные операторы (\if, \else) позволяют генерировать разные версии документа из одного исходника (например, для разных платформ или локалей). Можно создавать свои макросы LaTeX — по сути, как функции в коде, чтобы автоматизировать повторяющиеся элементы. А благодаря интеграции с языками (например, Python и Lua) можно встраивать в документ динамически генерируемый контент: графики, таблицы и пр. В общем, тут можно бесконечно автоматизировать — звучит, как мечта любого программиста.

LaTeX является стандартом де-факто в наборе научных и технических документов благодаря хорошей поддержке математических формул и точной типографике. Но его возможности гораздо шире! Мы рекомендуем рассматривать LaTeX, если вы хотите:

• «Professional looking pdf» с графикой, таблицами, диаграммами и пр.

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

Когда проигрывает LaTeX:

• Для простых документов: Одностраничные README или быстрые заметки удобнее писать в Markdown.

• Интерактивность: LaTeX — для статичных PDF. Если нужен веб с динамикой, то выбирайте HTML+JS.

Итак если вы создаете комплексный документ и хотите полностью управлять форматированием и использовать все доступные средства визуализации, то однозначно стоит попробовать LaTeX. Мы намеренно не приводим здесь код LaTeX. Вы сами сможете оценить насколько это сложная/простая экосистема на примерах из нашего шаблона (ссылка в конце статьи).

Контейнеризация (Development Containers)

Простые языки разметки вроде markdown много где поддерживаются нативно, чего нельзя сказать о LaTeX. Тут мы вынуждены сначала установить его в систему.

Чтобы избежать проблем с установкой и настройкой LaTeX на разных платформах (Win, Mac, Linux), мы будем использовать контейнеризацию. Вся сборка документа будет происходить внутри контейнера, который будет единым для всех технических писателей и разработчиков, и больше никаких сообщений вроде «На моём ноутбуке всё работает, а у тебя — ошибка компиляции».

Чтобы работать с контейнером стало еще удобнее, мы воспользовались Development Containers (dev containers).

Dev container — это предварительно настроенная среда разработки в Docker-контейнере, которая подключается к вашей IDE. Простыми словами, разработчик, сидя за своим ПК, ведет разработку внутри контейнера с преднастроенной целевой системой и всеми необходимыми зависимостями. Например, работая на виндовом ноутбуке, можно запускать сборку под Ubuntu, использовать bash скрипты и пр. И все это не выходя из своей любимой IDE!

Мы использовали dev containers совместно с VS Code. Там отличная интеграция и вся настройка сводится к установке необходимого расширения. После можно открыть проект, в котором есть dev container и выбрать в всплывающем окне «Reopen in Container». Мы также успешно запускали dev containers в CLion от Jetbrains. Полный список поддерживаемых инструментов можно посмотреть на официальном сайте.

Какие плюсы нам даст контейнеризация:

• Единое окружение для всех. Неважно, что установлено локально на PC разработчика. Dev container содержит все нужные пакеты LaTeX внутри контейнера. Как итог — документация собирается одинаково на Windows, macOS и Linux.

• Быстрый старт без ручной настройки. Достаточно открыть проект в VS Code (или CLion) — Dev container запустится автоматически и можно сразу приступать к редактированию.

• Тот же контейнер в пайплайне. В GitHub Actions/GitLab CI используем тот же образ, что и в Dev container и получаем PDF, идентичную локальной сборке.

Основной минус работы через dev container — снижение производительности. Хотя на нашем опыте чистая сборка 100 страничного документа с графикой не вызывала дискомфорта и укладывалась в 1 минуту.

Dev container очень удобная вещь и позволяет избежать проблем с настройкой тулчейна на локальной машине. Мы также активно использовали такой подход при кроссплатформенной разработке на C++.

Подробнее про использование дев контейнеров можно узнать в статье.

Шаблон LaTeX для быстрого старта

Мы подготовили репозиторий с dev container и шаблоном LaTeX документа с примерами верстки. Проект содержит небольшой readme и распространяется по лицензии MIT (что означает свободное использование, изменение и распространение).

Мы хотим поделиться этим шаблоном, чтобы облегчить старт тем, кто захочет попробовать LaTeX.

Все что требуется — запустить VS Code, установить расширение «Dev Containers», клонировать репозиторий, открыть его в VS Code и согласиться с pop-up «Reopen in Container». Через некоторое время контейнер будет собран и вы получите возможность создать красивую PDF из примера в пару кликов.

Какие полезности есть в нашем шаблоне:

• титульный лист с логотипом

• автоматически генерируемое содержание (table of contents)

• водяной знак (watermark) на всю документацию

• автоматическая генерация PlantUML диаграмм из текстового описания

• автоматическая вставка файлов формата *.drawio в финальную pdf

• моноширинный шрифт для форматирования кода

• примеры основных конструкций (заголовки, списки, таблицы и пр.)

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

Наш опыт документирования

На одном из проектов мы использовали LaTeX для документирования разрабатываемой нами C++ библиотеки. С помощью условных операторов мы смогли объявить некоторые главы документа как внутренние и внешние. Внешние главы содержали информацию, необходимую заказчику для внедрения нашей библиотеки, а внутренние главы — детали реализации, необходимые только нам, как разработчикам. В пайплайне мы генерировали два файла pdf: первый для использования внутри команды, а второй отправляли заказчику вместе с библиотекой. Много времени нам сэкономила генерация диаграмм PlantUML из текстового описания. Еще мы подтягивали версию библиотеки из переменной окружения и она автоматически вставлялась на титульный лист в pdf и её не приходилось править вручную.

А вот еще пример автоматизации из нашей офисной жизни: мы взяли шаблон из этой статьи, и дописали его до полноценного Python-API для генерации документов компании.
Работает так: в API стучим в эндпоинт с JSON-request данными для заполнения (например, данные по сотруднику). Эти данные парсятся, превращаются в список тэг-значение, документ LaTeX при генерации подставляет вместо тэгов значения. На выходе получаем трудовой договор и NDA-договор в виде pdf с уже заполненными полями. Так можно исключить рутину по ручному копированию данных и снизить вероятность ошибки. Такой же подход планируем внедрить в свою внутреннюю операционную/HR-систему Inner Circle  — которая уже хранит все нужные данные и сама все подставит.
Какие плюсы от внедрения LaTeX в этом сценарии?

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

• Смогли выделить в документах повторяющиеся компоненты (например, шапку, место для подписи) и переиспользовать их в разных типах документов через простой import. Получилась такая междокументальная дизайн-система.

Выводы

Какое заключение мы сделали для себя:

Docs as code — однозначно стоит применять, желательно с начала проекта, пока еще нет большой базы знаний в какой-то wiki-системе (иначе придется мигрировать).

LaTeX — хорош для навороченных статичных PDF, но требует времени на освоение. Для простых задач, таких, как одностраничные заметки или README-файлы, Markdown остается более практичным выбором.

Dev Containers — рекомендуем к использованию, избавляет от проблем с настройкой тулчейнов на локальной машине.

Если взять все вместе, то получаем бесплатное и функциональное решение для красивой профессиональной PDF на выходе.

Спасибо за внимание, будем рады услышать ваш опыт «борьбы» с документацией в комментариях. Мы продолжаем совершенствовать этот процесс и открыты для обмена лучшими практиками.

Репозиторий с готовым шаблоном LaTeX:
https://github.com/TourmalineCore/docs-as-code-latex-template

Автор статьи: Антон Кирпичников
Редактура: Мария Ядрышникова
Вычитка и фидбек: Юлия Магденко, Александр Петраков
Оформление: Анастасия Тупикина