Хабр, привет! На связи коллективный разум технических писателей компании «Базис». Над представленным в этой статье проектом мы работали вместе, так что и рассказывать о нем будем вместе. Если точнее, расскажем о том, как познавали методологию Docs-as-Code, зачем техническим писателям дружить с DevOps-инженерами, а главное, почему мы перешли от reStructuredText к AsciiDoc и что нам это принесло.

Да кто такой этот ваш Docs-as-Code?

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

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

Вместо того, чтобы хранить все в отдельных файлах, которые редактируются вручную и рассредоточены по разным компьютерам, вся документация складывается в единое хранилище — в тот же репозиторий, что и основной код. Release notes и другие тексты представляют собой не громоздкие документы Word или PDF, а файлы в форматах Markdown или Acsiidoc. Потом с помощью других инструментов (например, конвертера Pandoc) эти файлы автоматически собираются в красивый и удобный документ в нужном формате.

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

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

Сейчас сложности, связанные с реализацией подхода Docs-as-Code в нашей команде, уже позади. Мы попробовали формат reStructuredText, но затем перешли на AsciiDoc; перебрали несколько инструментов, чтобы остановиться в итоге на платформе GitLab, редакторе VSCodium и некоторых других. Но путь даже к такому небольшому набору был непростым.

Первый подход к снаряду

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

• Язык разметки reStructuredText (RST)  — был выбран из-за простого синтаксиса, плюс он хорошо поддерживался различными текстовыми редакторами, в частности, Geany.

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

• Pandoc — универсальный конвертер документов, поддерживает множество различных форматов, включая reStructuredText и AsciiDoc. Мы использовали его вместе с кастомными решениями с фильтрами на языке Lua для получения документов целевого формата (DOCX и PDF).

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

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

• Метод «Scripts run scripts» предполагал использование цепочки скриптов для автоматизации процессов написания документации. Он позволял нам упростить и ускорить процесс создания и обновления текстовой информации, а также обеспечить её единообразие и стабильность.

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

• отсутствие TOC (Table of Content) на гиперссылках;

• отсутствие автонумерации картинок и таблиц;

• наличие «битых ссылок»;

• разнородность стилей в документе;

• проблемы с генерацией титульной страницы.

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

Инженеры спешат на помощь

На этот раз решили не обходиться только своими силами, а позвали на помощь наших коллег, DevOps-инженеров, которые:

• провели экспертизу и рекомендовали формат AsciiDoc;

• помогли организовать новый репозиторий и установить все необходимые инструменты, тот же редактор VSCodium и его расширения;

• подготовили стили для документов с учетом принятых в компании стандартов;

• написали CI/CD-конвейер для сборки документов;

• сопровождали и обучали технических писателей на первых этапах перехода.

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

Этапы перехода от reStructuredText к AsciiDoc

Дальше нужно было организовать процесс переноса документации из RST в ADOC. Задача кажется несложной, ведь это просто конвертация из одного формата в другой. Но на практике пришлось разбить процесс на несколько этапов:

1. Заморозка актуальной версии (выпуска/релиза), оформленной с применением разметки reStructuredText, чтобы зафиксировать текущее состояние документации и подготовиться к ее обновлению. Мы с командой разработки продукта пришли к соглашению о «заморозке» работы над обновлением документации сроком на три месяца.

2. Разработка структуры документации. Вместе с продуктовыми аналитиками мы определили, какие главы и разделы будут включены в документ. Это помогло нам правильно организовать информацию и сделать ее более доступной для пользователей.

3. Составление карт документов. На этом этапе мы утвердили состав и порядок сбора основного документа. Карты документов помогли организовать информацию и упростили создание документации.

4. Конвертация исходных текстов из reStructured в AsciiDoc. С этой задачей мы справились самостоятельно, используя инструмент Pandoc, который позволяет конвертировать тексты из одного формата в другой. На выходе получился алгоритм «1 документ = 1 файл .adoc».

5. Оформление полученных текстов. На этом этапе наша команда ознакомилась с официальной документацией AsciiDoc и выбрала «лучшие практики», а заодно сформировала базовые навыки работы с форматом. Все это стало частью регламента разработки документации и в итоге помогло создать качественные тексты.

6. Дробление исходных текстов на главы. Этот этап очень важен, так как позволяет изолировать взгляд от большого объема информации, сделать документ более удобным для чтения и навигации. Мы применили принцип «1 глава = 1 файл .adoc» и придерживаемся его до сих пор.

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

Старое vs Новое

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

Для наглядности — общий вид структуры до и после изменения процессов документирования:

Особенности старой структуры проекта

• Одна основная директория разработки документации.

• В этой директории содержатся файлы JSON для настройки титульного листа и версии продукта, а также директория для хранения медиаконтента.

• Готовый файл документации в формате .rst.

Особенности новой структуры проекта

• Наличие главной (корневой) директории, внутри которой лежит комплект документации.

• Комплект документации включает директорию разработки документации, внутри которой находятся директория для разработки глав (chapters), карта разработки документации (main) и директория для разработки приложений к документации (appendix).

• Для хранения медиаконтента используется отдельная директория с поддиректориями по группам скриншотов (media).

• Наличие директорий с PDF-темами и CSS-стилями, а также файла с версией документируемого продукта.

Что мы получили в результате

Использование нового языка разметки AsciiDoc в сочетании с VSCodium помогло улучшить скорость написания и согласования release notes, а также в целом повысило качество документации в компании — на радость нашим коллегам.

В частности, благодаря формату AsciiDoc мы смогли:

• автоматизировать нумерацию элементов — картинок и таблиц;

• автоматизировать сборку PDF и упростить процесс выходного контроля документов;

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

• автоматизировать генерацию титульных страниц с учетом корпоративного стиля компании;

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

• создать удобную навигацию по документу.

Что касается VSCodium, то одним из ключевых преимуществ редактора для нас стало использование сниппетов — заранее определенных фрагментов кода, которые можно быстро вставлять в текст. Кроме того, с VSCodium можно генерировать превью документов в реальном времени, т. е. мы получили возможность сразу видеть, как будет выглядеть итоговый документ в HTML- или PDF-формате, и оперативно вносить необходимые коррективы.

В процессе перехода на AsciiDoc мы разработали два внутренних регламента:

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

2. Регламент взаимодействия технических писателей и аналитиков, которые ставят задачи на документирование.

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