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

Материалы статьи основаны на встрече-вебинаре, который я проводила с другими техническими писателями.

Что такое Docs as Code

Я встречала довольно много определений этого подхода. Несомненно, каждое из них имеет свой смысл, но мне больше всего нравится определение, которое я предлагаю использовать в этой статье.

Docs as Code — это подход к документации, который использует инструменты разработчика для решения проблем документирования.

Какие инструменты разработчика может использовать технический писатель

Генераторы статических сайтов (Static Site Generators – SSGs) для создания сайта с документацией

При работе с Word или Confluence лично я постоянно сталкиваюсь с проблемой стилей. Хочется создавать красивую документацию, но в Confluence то и дело возникают хаотичные пустые строки, а в Word “слетают” стили.

Чтобы решить эту проблему, можно использовать генератор статических сайтов (SSG). Этот универсальный инструмент применяет к вашему документу единообразные стили, гарантируя эстетичное отображение. Конечно, SSG решает и многие технические проблемы, но об этом – чуть позже.

Пример сайта с документацией на Hugo:

Screenshot-2025-07-06-at-19-08-46

Языки разметки (Markup Languages) для подготовки контента

Чтобы сгенерировать сайт с помощью SSG, необходимо предоставить документ, созданный с использованием одного из поддерживаемых языков разметки. Языки разметки позволяют использовать контент в разных форматах. SSG применяет заданные стили к документу, написанному на Markdown, reStructuredText или AsciiDoc, и создает страницы в HTML. При использовании других инструментов на основе того же контента можно генерировать PDF и DOCX.

Пример разметки Markdown:

image

Пример разметки reStructuredText:

image-2

Пример разметки AsciiDoc:

image-3

Системы контроля версий (Version Control Systems – VCS) для совместной работы

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

Инструменты для проверки качества документации (Documentation Linting) для поддержки качества документации

В рамках подхода Docs as Code в CI/CD пайплайн сборки проекта можно встраивать инструменты для проверки, например, орфографии. Это открывает довольно широкий набор возможностей по поддержке качества документации.

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

С чего начать

Если вы впервые столкнулись с этим подходом и хотите оценить сложность инструментов, то советую изучать инструменты в следующей последовательности:

Чтобы оценить сложность разметки: пройдите тренажер по Markdown

прочитайте базовое описание reStructedText и Asciidoc Чтобы понять полный цикл разработки документации, попробуйте выполнить инструкции из раздела Начало работы в документации Diplodoc. Попробуйте собрать сайт на одном из SSG, например, Hugo. Для этого шага можно выбрать Quick Start любого SSG. Чтобы упростить работу с остальными инструментами, скачайте VS Code, и прочитайте обзорную статью, например, на Хабре. Пройдите базовый курс по Git, например, от Яндекс Практикума. Прочитайте про хранилища репозиториев BitBucket и GitHub. Прочитайте, что такое Gramax. Этот инструмент часто используют в случае, когда хочется выбрать вариант попроще. Изучите документацию популярных SSG или статью на Хабре:

Это поможет сравнить инструменты между собой и оценить их полезность для ваших задач.

Мой опыт с Docs as Code

Как я уже говорила, у меня есть опыт работы как в компаниях, уже применяющих Docs as Code, так и истории о моем собственном опыте внедрения. Историй много, но сейчас я расскажу три основных, которые меня многому научили.

Техническая поддержка технических писателей

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

В этом плане мне очень понравился подход Яндекс Крауда. У них внедрен Docs as Code, но при этом команда писателей постоянно увеличивается. Поэтому проблему с инструментами они решили красиво:

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

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

Проблемы организации работы с DevOps-инженерами

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

Самой печальной проблемой, с которой я сталкивалась в работе с DevOps-инженерами, была их недостаточная мотивация в поддержке документации. Нет ничего приятного в том, чтобы неделями добиваться работоспособности тестового стенда. Еще тогда в репозиториях было настроено автоматическое обновление компонентов, что приводило к обновлению SSG и периодическому падению сайта. Решение этой проблемы далось с большим трудом.

Поэтому я рекомендую оценить возможные сложности совместной работы над инфраструктурой. Это может оказаться решающим фактором.

Документация для разработчиков

На текущем месте работы мы используем Confluence. Практически нет никакой необходимости в подходе Docs as Code для документации, которую мы пишем для заказчиков, поэтому я долго не трогала это направление. Однако недавно ко мне обратились разработчики с просьбой создать документацию для модулей, для реализации которой трудно найти решение лучше, чем Docs as Code.

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

Я собираюсь упростить процесс документирования для разработчиков с помощью Docs as Code:

В папке каждого модуля в коде появится шаблонизированный YAML-файл, который разработчики будут заполнять. Он будет содержать общее описание модуля и его настройки. В репозитории с документацией YAML-файлы будут преобразовываться в HTML по шаблонам с помощью Hugo.

Я думаю, готовый шаблон в формате YAML будет простым для заполнения для людей, профессионально не пишущих тексты. Эта идея пока находится на стадии реализации, но я хотела привести ее в качестве примера использования Docs as Code.

Заключение

Docs as Code — подход, который может быть сложным в реализации, но позволяет решать оригинальные задачи и создавать привлекательную документацию. Более того, изучение этого подхода не только расширит ваш кругозор, но и поможет лучше понимать процессы разработки ПО.

Спасибо за внимание! 🙂

Webinar | A Step-by-Step Introduction to Docs as Code with Practical Examples and Personal Experience

Docs as Code: A New Era in Developer Documentation

Docs as Code is an approach that leverages developer tools for creating and maintaining documentation. It combines static site generators and markup languages to ensure consistent content formatting.

Вебинар | Пошаговое введение в Docs as Code с практическими примерами и личным опытом

Docs as Code: новая эра создания документации для разработчиков

Docs as Code – это подход, позволяющий использовать инструменты разработчика для создания и поддержки документации. Он объединяет генераторы статических сайтов и языки разметки для единообразного оформления контента.

Подробнее в ТГ: @DevPulseAI

habr #russianTech