0061 — Docs as Code

В профессии технического писателя сейчас набирает силу методология «Docs as Code» (DaC). Сегодня разберём, что в эту методологию входит, а что имеет признаки DaC, но при этом им не является.

Начнём с определений. Мне нравится определение, данное Семёном Факторовичем в его статье на Habr:

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

Допустим, вы создаёте документы в Microsoft Word или LibreOffice Writer, а потом добавляете новые версии файлов в репозиторий Git и публикуете на сервер. Это Docs as Code?

Разумеется, нет!

Использование систем контроля версий (Git, SVN, Mercurial, Bazaar) — необходимое, но недостаточное условие. Вторым важным условием является использование одного из легковесных языков разметки.

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

Пусть у нас есть такой код в формате Markdown:

Этот текст будет **жирным**.

Две звёздочки слева и справа от слова «жирным» — обычный текст, но при сборке получится так:

Этот текст будет жирным.

Существуют и другие, более сложные форматы разметки (в алфавитном порядке):

• AsciiDoc;
• DITA;
• DocBook;
• ReStructured Text.

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

Третий компонент DaC — способ публикации изменений и доставки итоговых документов конечным пользователям. В разработке ПО существует подход «CI/CD», при котором любой коммит, попавший в основную ветку проекта, в течение очень короткого времени попадает в конечный продукт. С документацией та же история: при попадании изменений в нужные ветки документация в выбранных форматах создаётся и публикуется автоматически.