Dokumentation als Code

1) Architektonische Prinzipien

1. Eine einzige Quelle der Wahrheit. Dokumente, Diagramme, Diagramme, API-Spezifikationen, Glossar - im VCS neben dem Code.
2. Automatische Qualitätskontrolle. Linters, Rechtschreibung, Link-Check, doctest Codebeispiele.
3. Montage als Artefakt. Die Dock-Site, PDF/ebook, „eingebettete Hinweise“ sind Teil der Release-Pipeline.
4. Versionierung und Traceability. Doc regiert die gleiche PR, die das Verhalten des Systems ändert; ADRs sind an Commits gebunden.
5. Verfügbarkeit nach Rolle. Öffentlich/intern, Runbook ™ und On-Call, API-Specs für Integratoren.
6. Ein Minimum an Handarbeit. Generierung von Inhaltsverzeichnissen, Diagrammen, Abhängigkeitsgraphen, Codefragmenten - aus Quellen.

2) Dokumenttypen und Repostruktur

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 - Diskutieren Sie Lösungen vor der Implementierung.
• ADR ist eine feste architektonische Entscheidung (Kontext → Entscheidung → Konsequenzen → Alternativen).
• Runbook/Playbook - Schritt-für-Schritt-Anleitung für Vorfälle und Operationen.
• How-To/FAQ - Aufgabe → Schritte → Überprüfung des Ergebnisses.
• API-Specs - OpenAPI/AsyncAPI/Proto als Quelle für die Generierung von SDKs und Docks.
• Diagramme als Code sind Mermaid/PlantUML/Graphviz/C4.

3) Stil und Standards

Einheitlicher Style Guide (Ton, Terminologie, Titelvorlagen, Beispiele).
Glossar mit kanonischen Begriffen (EN/RU), Alias, verbotenen Formulierungen.
Nummerierung und Referenzen: permanente Anker, Querverweise zwischen ADR/RFC/Code.

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

4) Montage und Veröffentlichung

• MkDocs (Material) - einfach, bequem, gute Navigation und Suche.
• Docusaurus - Version der Dokumentation und docs + blog; MDX-Komponenten.
• Antora ist eine modulare Dokumentation für große Plattformen.

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) Diagramme und Diagramme als Code

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 werden in die Site gerendert; aus diesen werden SDKs/Clients/Beispiele generiert.

6) Qualität: linters und Dokumentationstests

• markdownlint - Regeln für die Formatierung von Markdown.
• Vale - Stil/Terminologie/Ton.
• Spellcheck - Rechtschreibung (RU/EN Wörterbücher).
• Linkcheck - externe/interne Links, Anker.
• Doctest/Examples - Ausführung von Code-Snippets, Synchronisation von CLI/API-Versionen.
• Schematest - Validierung von 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 startet 'python -m doctest docs/snippets/calc. py`.

7) Prozesse: RFC/ADR/Reviews und SLA für Obsoleszenz

RFC flow: der Initiator → das Konzept → die Erörterung → die Lösung → der Plan → implementazija → der Posten-faktum des Retro.
ADR-Flow: Auswahl kurz erfassen + Link zu RFC/Experimenten.
Review-Verfahren: Die Quelle ist 'CODEOWNERS' + 'doc-owners. yaml`.
SLA auf Obsoleszenz: Kritische Artikel haben 'last _ review' und eine Alert auf Revue nach N Tagen.

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) Lokalisierung (i18n) und Mehrsprachigkeit

Lokalisierungsstrategie: Ausgangssprache (EN oder RU) → Übersetzung durch Zweige' i18n/< locale>'.
Schlüssel und Kontext: „Stable-ID“ für Überschriften/Fragmente speichern.
Checks: Schritt 'fehlende-Tasten', Warnungen auf nicht synchron.
Lokale Stile: lokale Glossare, ungültige Callouts, Codebeispiele in der lokalen UI-Sprache.

9) Integration mit dem Produkt

Integrierte Hilfe (in-app docs): MDX-Komponenten, kontextbezogene Hinweise.
Versionierung nach Releases: Tags/Branches' docs/vX. Y', eine Website mit Selektor-Versionen.
Autogenerierung von Sektionen: von OpenAPI/AsyncAPI, GraphQL SDL, CLI '--help'.
Changelog als Code: automatische Generierung nach PR-Tags (feat/fix/docs/breaking).

10) Metriken und Beobachtbarkeit der Dokumentation

Docs SLO: Zeitpunkt der Erstellung/Veröffentlichung, Site-Aptime, Zeitpunkt des Erscheinens des Dokuments nach der PR.
Artefaktabdeckung: Anteil der Dienste mit ADR, Anteil der Endpunkte mit Beispielen, Anteil der Runbooks mit „Gesundheitscheck“.
Benutzerdefinierte Metriken: unbeantwortete Suchanfragen, Ansichtstiefe, CTR der integrierten Hinweise.
Qualität: Linterfehler/1000 Zeilen, „defekte Links“, Anteil veralteter Artikel.

11) Sicherheit und Privatsphäre

Geheimnisse und PD sind in Repos verboten; linters auf Geheimnisse und Tarnung.
Zugriff auf die interne Website über SSO; Öffentliche Bereiche sind getrennt.
Exportbestimmungen: PDF/Archive ohne interne Links, Wasserzeichen für vertrauliche Dokumente.
Screenshot Hygiene: automatische Anonymisierung (Mock-Daten/blur).

12) Muster

Docs in PR. Jede Änderung, die sich auf das Verhalten auswirkt, beinhaltet die Aktualisierung der Docks in derselben PR.
Vorlagen als Vertrag. Die Erstellung von Service/Endpoint/Dataset erfolgt über einen Generator, der die Dock-Rohlinge legt.
Diagramme als Code. Jede Zeichnung ist eine editierbare Quelle, eine SVG/PNG-Baugruppe in CI.
Docs Preview. Bot-Kommentar mit Link zur Website-Vorschau für PR.
Dock-Links im Code. Anmerkungen in den Quellen ('@ doc: adr/0007'), die in die Site gerendert werden.

13) Anti-Muster

Die Dokumentation im Wiki/Notion ohne Versionen neben dem Code → nicht synchron.
Screenshots ohne Quellen → die Unfähigkeit, automatisch zu aktualisieren.
„Geheimes“ Wissen in mündlichen Chats und privaten Dateien.
Generika ohne Beispiele und Invarianten → nutzlose Seiten.
Fehlende Eigentümer und „last _ review“ → eine Lawine der Obsoleszenz.
Manuelle Montage und Veröffentlichung → spröde und seltene Veröffentlichung von Docks.

14) Beispiele für Automatisierung

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) Checkliste des Architekten

1. Gibt es ein einziges Dock-Repository neben dem Code und eine klare Struktur?
2. Vorlagen (RFC/ADR/Runbook/How-To) und Glossar werden beschrieben?
3. Sind Linter (markdownlint, Vale), Spellcheck, Linkcheck und Doctest enthalten?
4. Diagramme und Diagramme - als Code, Montage in CI?
5. Werden API-Specs (OpenAPI/AsyncAPI/Proto) validiert und in eine Site gerendert?
6. Organisiert docs-preview für PR und auto-publishing für merge?
7. Gibt es SLAs für Obsoleszenz (last_review) und „Besitzer“ von Seiten?
8. Metriken: Berichterstattung, Linterfehler, gebrochene Links, Suchanfragen „Null“?
9. Sicherheitsrichtlinien: Geheimnisse verboten, SSO, Wasserzeichen/Export?
10. Wird die Lokalisierung über Äste gesteuert und auf Lücken geprüft?

Schluss

Docs-as-Code verwandelt Dokumentation von „Post-Factual Notes“ in ein funktionierendes Entwicklungsartefakt: versioniert, getestet und ausgeliefert. Mit diesem Ansatz wird Wissen in der Nähe von Code gelebt, Änderungen sind transparent und Benutzer und Ingenieure erhalten aktuelle Anweisungen, Diagramme und Beispiele, wenn sie benötigt werden. Dies reduziert das Betriebsrisiko, beschleunigt das Onboarding und verbessert die Qualität der Lösungen auf der gesamten Plattform.