“Документация как код” (“docs as code” или “docs like code”) - подход в создании и поддержке технической документации с использованием систем, инструментов, процессов, которые применяются в разработке программного кода.

Признаки подхода “документация как код”:

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

Ведение документации в текстовых данных

Текстовые данные (тектовые форматы или plain text) - это текст, к которому не применено форматирование (например, различные шрифты, их размеры, цвет, жирность, курсив и т.д.). Этот тип текста прост в использовании, легко читается. Поэтому часто применяется многимим программистами и разработчиками в их работе. Примерами здесь могут служить широко распространённые облегчённые языки разметки - Markdown, reStructuredText, Textile, Fountain и др.

Использование интегрированной среды разработки (IDE) для работы с текстами

Как правило, в качестве редактора выступает IDE, которая используется смежной командой разработчиков. Например, Atom, Sublime Text, Visual Studio Code и другие (в основном бесплатные).

Использование системы контроля версий

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

Использование статических генераторов сайтов

Вместо систем управления содержимым (CMS) для публикации документации применяются генераторы статических сайтов. Например, Jekyll, Sphinx и т.д.

Выполнение автоматического тестирования документации

Ручная проверка документации заменяется на автоматическую в виде скрипта, который проверяет сломанные ссылки, ошибки стилей и т.д.

Применение методологии разработки ПО

Применение методологии разработки ПО (например, agile), а также инструментов управления командой разработчиков (например, Jira) в рабочих процессах написания технической документации.

Если обозначенные выше признаки включены в процесс разработки технической документации, то с большой долей вероятности можно сказать, что применяется подход “документация как код” или “docs as code”.