🧠 Skills: Docs-as-Code — почему Confluence умирает и что приходит на смену

Коллеги, понедельник — хороший день для темы которая отделяет зрелые инфраструктуры от хаотичных. Документация.

Главная боль технической документации известна каждому: во-первых, её нет. Во-вторых, если она есть — она не актуальна. Confluence-страница, обновлённая последний раз в 2023-м, хуже чем отсутствие документации — она вводит в заблуждение.

Docs-as-Code решает это радикально: документация живёт там же где код, в том же git, проходит те же review.

Docs-as-Code — это методология которая говорит документировать так же как ты обращаешься с кодом — используя те же инструменты, workflow и системы контроля версий что разработчики используют для написания кода. Документация хранится в plain text (Markdown, AsciiDoc), в git-репозитории, с современным тулингом для генерации HTML, PDF.

Честная оговорка чтобы не было иллюзий: Docs-as-Code не обновляет документацию автоматически так же как обновляется код. Когда разработчик добавляет новый API endpoint — документация не сгенерируется сама, если для этого не настроены конкретные workflow и автоматизация.

Практический старт для сисадмина — не нужен GitBook за деньги:

МИНИМАЛЬНЫЙ DOCS-AS-CODE СТЕК (всё бесплатно):

Хранение:    Gitea / GitLab (self-hosted)
Формат:      Markdown (или AsciiDoc если нужны include и переменные)
Генерация:   MkDocs (Material theme) — статичный сайт из .md
Диаграммы:   Mermaid / PlantUML (текстом, версионируются)
CI/CD:       git hook → автодеплой при push

СТРУКТУРА РЕПОЗИТОРИЯ:
  docs/
  ├── infrastructure/
  │   ├── network-topology.md      # + Mermaid диаграмма inline
  │   ├── servers-inventory.md
  │   └── backup-strategy.md
  ├── runbooks/
  │   ├── RB-001-db-failover.md
  │   └── RB-002-cert-renewal.md
  ├── procedures/
  │   └── onboarding-new-server.md
  └── mkdocs.yml

# Поднять MkDocs за 5 минут:
pip install mkdocs-material --break-system-packages

# Инициализируем проект:
mkdocs new infra-docs && cd infra-docs

# Правим mkdocs.yml — тема Material:
cat > mkdocs.yml << 'EOF'
site_name: Infrastructure Docs
theme:
  name: material
  features:
    - search.suggest
    - content.code.copy
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
EOF

# Локальный предпросмотр:
mkdocs serve  # http://127.0.0.1:8000

# Деплой как статика (git hook или CI):
mkdocs build  # генерит site/ — отдаём через nginx

# Диаграмма прямо в markdown (Mermaid):
# ```mermaid
# graph LR
#   Internet --> Firewall --> LB --> Web1 & Web2 --> DB
# ```

Один принцип который делает Docs-as-Code живым: хорошая документация должна непрерывно эволюционировать вместе с кодом который она описывает. Правило простое — изменил инфраструктуру, обнови doc в том же PR. Не «потом», а в том же коммите. Review не пропускает PR без обновления документации.

Зачем это сисадмину а не только разработчику: твои runbook, топология сети, процедуры onboarding — это и есть код инфраструктуры. В git они версионируются, ревьюятся, и главное — видно кто и когда менял. Confluence этого не даёт.

Итог: MkDocs + Gitea + правило «doc в том же PR» = документация которая не устаревает. Это вечер настройки и смена привычки. Попробуй на одном runbook на этой неделе.

#skills #docsascode #документация #mkdocs #git #sysadmin #admin_future