🙂 Docs as Code

Docs as Code – подход к созданию и сопровождению документации.
🟢для работы с документами используются те же инструменты и процессы, что и для программного кода.
🟢текст пишут на языке разметки (Markdown, AsciiDoc), хранят в Git-репозитории и собирают с помощью генераторов сайтов (например, GitLab Pages, Docusaurus, Antora)
🟢публикуемая версия всегда синхронизирована с кодом и доступна потребителям


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

Ообращение с текстом документации, как с исходным кодом приложения:
💠хранится в системе контроля версий
💠проверка изменений через pull request’ы
💠автоматизированно собирать и публиковать и т.д.

❕ Документация может храниться как в одном репозитории с кодом, так и в отдельном
Но всегда должна быть актуальной и согласованной с кодом (как и наоборот)


Суть подхода

Документация:
🔵хранится в репозитории Git
🔵пишется в IDE (VS Code или IDEA) с настроенными плагинами
🔵пишется на выбранном языке разметки, диаграммы описываются в формате кода (PlantUML, mermaid и др.)
🔵собирается при помощи генератора сайтов (например, Docusaurus)


Принципы написания документации

Написание спецификаций следует принципам написания кода, но имеет свои специфичные принципы

〰 Принципы из разработки

🟢DRY (Don’t Repeat Yourself)
Не дублируем информацию: один факт — один источник, остальные ссылаются

🟢KISS (Keep It Simple, Stupid)
Держим форму и язык простыми, без лишних деталей.

🟢YAGNI (You Aren’t Gonna Need It)
Пишем только то, что нужно прямо сейчас; гипотезы и «на будущее» убираем

🟢SRP (Single Responsibility Principle)
Один раздел — одна тема или функция

🟢SLAP (Single Level of Abstraction Principle)
Уровни абстракции не смешиваем: обзор и детали храним раздельно

🟢LoD (Law of Demeter)
Ссылаемся только на ближайший нужный контекст, избегаем дальних зависимостей


〰 Принципы, относящиеся к спецификациям

🟢читабельность — короткие абзацы, активные глаголы, минимум терминов
🟢единый стиль кодирования (структура текста, отступы, пробелы и т.д.) для облегчения понимания. Разрабатываются единые шаблоны документации и готовые блоки кода
🟢диаграммы как код — PlantUML, Mermaid, LikeC4: диаграммы генерируются из текста
🟢автоматизация пайплайна — CI проверяет орфографию, битые ссылки, формат
🟢отслеживание изменений, обновлений и исправлений в документах при помощи Changelog
🟢опубликованная версия документации является актуальной проду
🟢Merge Request, вливаемые в master, проходят ревью - без получения аппрува сделать mr нельзя
🟢Merge Request с изменениями в документации привязываются к задачам в Jira


Хранение документации

✳️ Рядом с кодом
Документация лежит в том же репозитории, что и сервис. Обычно в каталоге /docs.

Каждая ветка и тег кода несут свою версию текстов.
➡️ пример: GitLab хранит руководство пользователя в том же репозитории, чтобы изменения в продукте и тексте шли синхронно.

✳️ В отдельном репозитории
Документация развивается в своём проекте (или нескольких), независимом от исходников сервисов

Когда подходит:
🔵 доков много, обслуживают сразу несколько продуктов
🔵 требуется выпускать или править тексты без привязки к релизам кода


📎 Материалы
1. Docs as Code: введение в предмет
2. Опыт аналитиков Альфы про доку в коде
3. Docs as Code: как вести фронтовую документацию рядом с кодом, чтобы репозиторий не раздуло — опыт Альфы
4. Documentation as code: практики и инструменты документирования в сфере финансовых технологий
5. Статья о Docs as code от техписов - сайт собран как код на Rst
6. Инструменты подхода Docs-as-code

#инфраструктура #документация

➿➿➿➿➿➿➿➿
🧑‍🎓 Глубже по теме Docs as Code смотрите в Базе знаний по системному анализу :
⏺преимущества и недостатки Docs as Code
⏺сравнение с Confluence и другими подходами
⏺как понять, что Docs as Code действительно работает
⏺обзор инструментов
⏺пошаговое руководство, как внедрить Docs as Code
⏺как выбрать подход к документации

А ещё там 140+ статей и 2500+ ссылок на материалы -- и всё разложено по полочкам, как мы любим.