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

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 перетворює документацію з «постфактум нотаток» в робочий артефакт розробки: версіонований, тестований і доставляється. При такому підході знання живуть поруч з кодом, зміни прозорі, а користувачі та інженери отримують актуальні інструкції, схеми і приклади тоді, коли вони потрібні. Це знижує операційні ризики, прискорює онбординг і покращує якість рішень по всій платформі.