Количество команд разработки в YADRO постоянно растет. У каждой свои продукты, сервисы и стеки технологий. Одни пишут на С, другие — на Java, третьи — на Go, а четвертые и вовсе строят свой космолет. Но все эти команды объединяет одно: им нужна техническая документация, и запросы к ней более-менее типичны. 

Раньше каждый документ требовал полноценного включения технического писателя, и на это уходило слишком много времени. Любой API с монотонным описанием команд — огромный вал работы. При этом писатель — ценный специалист в команде, его компетенции нужны в более сложных документах. К тому же, традиционный способ разработки документации здесь не подходит еще и из-за необходимости проверки большого объема однотипных документов на полноту и соответствие продукту. При ручном описании референсов нет никакого способа, кроме метода пристального взора, убедиться, что затронуты все методы или команды.

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

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

Автоматизация создания документа эффективна, если текст легко формализовать и оформить по шаблону. Например, если в руководстве пользователя много авторского изложения, такие документы технические писатели создают без инструментов автоматизации. В тексте речь пойдет только о тех документах, которые можно генерировать. В основном это справочники API или CLI, но могут быть и readme, описания фич или программы и методики испытаний.

Принцип «одного окна» в документации

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

Замысел напоминал МФЦ, где один сотрудник помогает посетителям по самым разным вопросам: регистрирует по месту жительства, выдает СНИЛС, восстанавливает паспорт или записывает ребенка в детский сад. За этими услугами скрывается множество людей и действий, но входная точка одна. 

Целью DocOps был единый процесс, при котором каждая команда разработки может обратиться в команду технической документации и сказать: «Хотим, чтобы все наши документы генерировались и публиковались сами». А дальше выполнить необходимые граничные условия и получить быстрый, простой и управляемый способ создания, вычитки и публикации документации на прод. 

Исходники документации как артефакт билда приложения

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

Мы сформировали подход, в котором разделяем типы билдов приложения и генерируем из них документы разной степени готовности:

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

• В момент готовности кода на стороне команды разработки собирается релизный билд, а из него — финальный публичный документ, привязанный к этому билду. 

Чтобы сервис «одного окна» был удобным для команд разработки, мы принимаем разные форматы исходников документации: DITA, Markdown, AsciiDoc, reStructuredText и даже странички в Confluence или постановки задач в Jira. По сути, мы стараемся поддержать то, что удобнее конкретной команде разработки. Это возможно благодаря нашему сборочному конвейеру,  достаточно универсальному и поддерживающему все необходимое.

В таком процессе технический писатель не ждет окончания разработки: он встраивается в работу команды, и на выходе мы получаем качественную документацию вместе с билдом (релизом). Писателю больше не нужно становиться «почти разработчиком» и изучать язык с архитектурой кода в достаточной мере, чтобы самостоятельно писать документы. И не нужно стоять над душой инженера, пока он не изложит в более-менее понятном виде суть всех изменений. Писатель больше не тратит время на составление перечня атрибутов, параметров и их типов: ему достаточно отредактировать уже подготовленные разработчиками описания сущностей в исходном коде. Так появляется автодокументация — документ создается из этих описаний автоматически, причем сразу в нескольких форматах. 

Граничные условия для команд разработки

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

• у команды есть устоявшиеся процессы разработки и CI/CD,

• команда разработки генерирует исходники документации при каждом билде приложения,

• сгенерированные исходники имеют типизированную файловую структуру,

• исходники документации команда пушит в отдельный репозиторий.

Подключение команды разработки к сервису автодокументации

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

1. Установочная встреча.

2. Генерация исходников документации.

3. Изменения на стороне команды разработки.

4. Публикация результата. 

Установочная встреча. Мы договариваемся, что результатом прогона CI/CD будет не только собранное приложение, но и сгенерированные исходники документации, ассоциированные с конкретным билдом.

Генерация документации. DocOps изучают стек разработки команды. Зачастую находятся средства автоматической генерации документации из коробки, либо готовые решения. Например, для проектов на Go можно использовать Cobra и шаблоны документов. Небольшая настройка, и мы получаем валидные исходники для технических писателей. Из тех же текстов впоследствии будет собираться интерфейс командной строки, а также графический интерфейс. Таким образом, мы получаем строгое соответствие документации действительности и абсолютную консистентность текстов. 

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

Изменения на стороне команды разработки: 

• Дополнение CI/CD. Он должен генерировать не только приложение, но и исходники документации.

• Отправка исходников документации: CI/CD пушит сгенерированные исходники в отдельный репозиторий исходников документации.

Публикация документации. Коммит (в репозиторий-сателлит), содержащий исходники документов, запускает универсальный CI/CD команды DocOps. Он публикует документацию в нужный раздел на портале документации в зависимости от того, в какой репозиторий пришел коммит.

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

Я подробнее рассказывала о DOC-инфраструктуре YADRO в своей прошлой статье. Из нее вы узнаете о нашем конвейере сборки, приложении для публикации документов и обязанностях DocOps-инженера.

Плюсы и минусы сервиса автодокументации

Мы реализуем описанный в статье подход с разными командами разработки, и он приносит ощутимую выгоду:

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

• Сокращение сроков доставки документации. Писатель редактирует исходники кода, покрытые комментариями, не пишет документацию из головы и не проводит многочасовые интервью с разработчиком. Это экономит время всех участников процесса документирования и сокращает срок доставки документации.

• Актуальность документации. Процессы разработки и документирования идут параллельно. Тексты публикуются вместе с релизом, их готовность входит в Definition of Done. 

• Консистентность текстов. Документация всегда строго соответствует тому, что есть в коде билда приложения. По сути документ и есть код, иное его представление: все атомарные сущности одинаковы и в коде, и в документации, и в CLI, и в GUI.  

• Управляемое представление документации. За счет хранения артефактов билда в отдельном репозитории мы разделяем автогенерируемый контент и управление представлением документации.

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

• Быстрое подключение автодоки. От запроса команды разработки на подключение автодокументации до получения первой ссылки на портале  в среднем уходит 2 часа.

Но есть и причины, почему наш подход может подойти не всем:

• Масштабность. Подход отлично работает, если у вас много команд и продуктов, которым регулярно нужна документация для разных типов API или CLI. Для компаний с небольшим объемом документов подобное решение может быть избыточным, да и результат может не окупить вложенного времени. 

• Сложность. Настроить автоматическую генерацию документации непросто. Сложно встроиться в процесс разработки и действительно никому не мешать. Сложно обеспечить поддержку любого запрашиваемого формата.

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

• Внешние зависимости. Нередко требуется участие DevOps-инженера команды разработки, который должен поддержать необходимые правки в CI/CD, а это внешние зависимости, которые иногда могут сильно усложнять процесс.

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

Это была первая статья из цикла, посвященного автогенерируемой документации. В следующей я постараюсь рассказать, как такая простая идея, достойная Капитана Очевидности, выглядит на практике. Как в действительности в одно окно засунуть и AsciiDoc, и reStructuredText, и DITA, и Markdown, и 15 репозиториев в манифесте.