Документация как код

1) Архитектурные принципы

1. Единый источник истины. Документы, схемы, диаграммы, спецификации API, глоссарий — в VCS рядом с кодом.
2. Автоматическая проверка качества. Линтеры, орфография, проверка ссылок, doctest примеров кода.
3. Сборка как артефакт. Док-сайт, PDF/ebook, «встроенные подсказки» — часть релизного пайплайна.
4. Версионирование и трассируемость. Док правит тот же PR, что меняет поведение системы; ADR привязаны к коммитам.
5. Доступность по ролям. Публичное/внутреннее, Runbook’и под on-call, API-спеки для интеграторов.
6. Минимум ручной работы. Генерация оглавлений, схем, графов зависимостей, кодовых фрагментов — из источников.

2) Типы документов и структура репо

docs/
index. md architecture/
overview. md contexts/( C4, contexts, boundaries)
components/
data/
schemas/ (JSON Schema, Avro, Proto)
lineage/ (dataflow. md, dq-policies. md)
security/
threat-models/
key-management. md api/
openapi/ (OpenAPI. yaml)
asyncapi/ (.yaml)
grpc/ (.proto)
processes/
rfc/ (RFC-YYYY-XX-Title. md)
adr/ (ADR-0001-title. md)
runbooks/ (incident-.md)
playbooks/
sops/ (standard operating procedures)
product/
user-guides/
how-to/
faq/
i18n/
en/, en/, tr/# assets localization/
diagrams/ (Mermaid, PlantUML, Graphviz)
images/
_templates/ (RFC/ADR/Runbook templates)

• RFC — обсуждение решений перед внедрением.
• ADR — зафиксированное архитектурное решение (контекст → решение → последствия → альтернативы).
• Runbook/Playbook — пошаговые инструкции для инцидентов и операций.
• How-To/FAQ — задача → шаги → проверка результата.
• API-спеки — OpenAPI/AsyncAPI/Proto как источник генерации SDK и доков.
• Диаграммы как код — Mermaid/PlantUML/Graphviz/C4.

3) Стиль и стандарты

Единое руководство по стилю (тон, терминология, шаблоны заголовков, примеры).
Глоссарий с каноническими терминами (EN/RU), алиасами, запретными формулировками.
Нумерация и ссылки: постоянные якоря, кросс-референсы между ADR/RFC/кодом.

yaml title: "Payment Service: Overview"
owner: "payments-team"
reviewers: ["platform", "security"]
last_review: 2025-10-15 tags: ["architecture","payments","pci"]

4) Сборка и публикация

• MkDocs (Material) — просто, удобно, хорошая навигация и поиск.
• Docusaurus — версияция документации и docs+blog; MDX-компоненты.
• Antora — модульная документация для крупных платформ.

yaml site_name: Platform Docs theme:
name: material features: [navigation. tabs, content. code. annotate, search. suggest]
plugins:
- search
- mermaid2
- mkdocs-awesome-pages-plugin
- macros nav:
- Review: index. md
- Architecture:
- Overview: architecture/overview. md
- Data: architecture/data/index. md
- API:
- REST: api/openapi/index. md
- Events: api/asyncapi/index. md

5) Диаграммы и схемы как код

mermaid sequenceDiagram participant C as Client participant G as API Gateway participant S as Service
C->>G: POST /orders
G->>S: createOrder()
S-->>G: 201 + order_id
G-->>C: 201 Created

@startuml
!include <C4/C4_Container>
Person(user, "User")
System_Boundary(system, "Platform"){
Container(api, "API", "HTTP")
Container(db, "DB", "Postgres")
}
Rel(user, api, "Uses")
Rel(api, db, "CRUD")
@enduml

OpenAPI/AsyncAPI рендерятся в сайт; из них генерируются SDK/клиенты/примеры.

6) Качество: линтеры и тесты документации

• markdownlint — правила форматирования Markdown.
• Vale — стиль/терминология/тон.
• Spellcheck — орфография (RU/EN словари).
• Linkcheck — внешние/внутренние ссылки, якоря.
• Doctest/Examples — выполнение фрагментов кода, синхронизация версий CLI/API.
• Schematest — валидация OpenAPI/AsyncAPI/JSON Schema/Proto.

yaml name: docs-ci on: [pull_request, push]
jobs:
lint:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: npm i -g markdownlint-cli
- run: markdownlint "docs//.md"
- run: pipx run codespell docs          true
- run: pipx run linkchecker docs/site          true build:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
- run: pip install mkdocs-material mkdocs-mermaid2-plugin
- run: mkdocs build --strict preview:
if: github. event_name == 'pull_request'
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: mkdocs build
- uses: actions/upload-pages-artifact@v3

python docs/snippets/calc. py def add(a,b):
"""Returns sum of a and b.

>>> add(2,3)
5
"""
return a+b

CI запускает `python -m doctest docs/snippets/calc.py`.

7) Процессы: RFC/ADR/обзоры и SLA на устаревание

RFC flow: инициатор → черновик → обсуждение → решение → план → имплементация → пост-фактум ретро.
ADR flow: коротко фиксируем выбор + ссылку на RFC/эксперименты.
Review-процедуры: источник — `CODEOWNERS` + `doc-owners.yaml`.
SLA на устаревание: критичные статьи имеют `last_review` и алерт на ревью через N дней.

markdown
ADR-0007: Select Event Log - Avro + Schema Registry
Date: 2025-10-31
Status: accepted
Context: the evolution of schemes without breaking consumers is required.
Solution: Avro + Schema Registry, backward compatibility.
Implications: tooling, compatibility tests, N services migration.
Alternatives: JSON Schema, Protobuf (rejected due to X/Y).

8) Локализация (i18n) и многоязычность

Стратегия локализации: исходный язык (EN или RU) → перевод ветками `i18n/<locale>`.
Ключи и контекст: хранить «стейбл-ID» для заголовков/фрагментов.
Проверки: шаг `missing-keys`, алерты на рассинхронизацию.
Стили локалей: локальные глоссарии, недопустимые кальки, примеры кода на локальном языке UI.

9) Интеграция с продуктом

Встроенная справка (in-app docs): MDX-компоненты, контекстные подсказки.
Версионирование по релизам: теги/ветки `docs/vX.Y`, сайт с selector версий.
Автогенерация секций: из OpenAPI/AsyncAPI, GraphQL SDL, CLI `--help`.
Changelog как код: автоматическая генерация по меткам PR (feat/fix/docs/breaking).

10) Метрики и наблюдаемость документации

Docs SLO: время сборки/публикации, аптайм сайта, время появления документа после PR.
Покрытие артефактами: доля сервисов с ADR, доля эндпоинтов с примерами, доля Runbook’ов с «проверкой здоровья».
Пользовательские метрики: поисковые запросы без ответов, глубина просмотра, CTR встроенных подсказок.
Качество: ошибки линтеров/1000 строк, «битые ссылки», доля устаревших статей.

11) Безопасность и приватность

Секреты и ПД запрещены в репо; линтеры на секреты и маскирование.
Доступ к внутреннему сайту через SSO; публичные разделы отделены.
Правила экспорта: PDF/архивы без внутренних ссылок, водяные знаки для конфиденциальных документов.
Санитария скриншотов: автоматическая анонимизация (мок-данные/blur).

12) Паттерны

Docs in PR. Любое изменение, влияющее на поведение, включает обновление доков в том же PR.
Шаблоны как контракт. Создание сервиса/эндпоинта/датасета — через генератор, который кладет заготовки доков.
Диаграммы как код. Любой рисунок — редактируемый исходник, сборка SVG/PNG в CI.
Docs Preview. Комментарий бота с ссылкой на предпросмотр сайта для PR.
Док-линки в коде. Аннотации в исходниках (`@doc: adr/0007`), которые рендерятся в сайт.

13) Анти-паттерны

Документация в wiki/Notion без версий рядом с кодом → рассинхронизация.
Скриншоты без исходников → невозможность обновить автоматически.
«Секретные» знания в устных чатах и приватных файлах.
Генерики без примеров и инвариантов → бесполезные страницы.
Отсутствие владельцев и `last_review` → лавина устаревания.
Ручная сборка и публикация → ломкий и редкий релиз доков.

14) Примеры автоматизации

bash build. sh scripts/render-openapi. sh api/openapi/.yaml > docs/api/openapi/index. md scripts/render-asyncapi. sh api/asyncapi/.yaml > docs/api/asyncapi/index. md

bash linkcheck --config. linkcheck. yml site/

yaml
- name: Deploy Preview run: mkdocs build && npx serve -s site -l 5000 &
- name: Comment with URL uses: peter-evans/create-or-update-comment@v4 with:
issue-number: ${{ github. event. pull_request. number }}
body: "Preview: http ://preview- $ {{github. run_id }}.local"

15) Чек-лист архитектора

1. Есть ли единый репозиторий доков рядом с кодом и понятная структура?
2. Описаны шаблоны (RFC/ADR/Runbook/How-To) и глоссарий?
3. Включены линтеры (markdownlint, Vale), spellcheck, linkcheck и doctest?
4. Диаграммы и схемы — как код, сборка в CI?
5. API-спеки (OpenAPI/AsyncAPI/Proto) валидируются и рендерятся в сайт?
6. Организован docs-preview для PR и авто-публикация по merge?
7. Есть SLA на устаревание (last_review) и «владельцы» страниц?
8. Метрики: покрытие, ошибки линтеров, битые ссылки, поисковые «нулевые» запросы?
9. Политики безопасности: секреты запрещены, SSO, водяные знаки/экспорт?
10. Локализация управляется ветками и проверяется на пропуски?

Заключение

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