Documentation Drift — ein Systemdefekt
Jeder Codebase-Kickoff: README mit umbenannter Config, API-Docs mit toten Endpoints, Getting-Started mit deprecated Dependency. Niemand log absichtlich — Code und Docs haben getrennte Lifecycles; unter Deadline gewinnt Merge, „Docs nach dem Deploy“ verliert immer.
Für DACH-Agenturen: Drift kostet Support-Slack, längeres Onboarding (~1 Woche Verlust ≈ messbare Personalkosten pro Hire) und Trust Decay — nach zwei kaputten Beispielen lesen Entwickler gar keine Docs mehr; externe API-Nutzer churnen still.
Steve Baka: Stoppt Disziplin-Theater (Checkbox, Quartals-Audit) — baut Derivation from source of truth.
Warum klassische Fixes scheitern
PR-Checkbox: Wird ohne Update gesetzt. Quartals-Audit: findet Probleme, wenn Schaden schon da ist. Docs-as-Code allein: gleicher Workflow, Menschen vergessen trotzdem.
Hebel: Automatisierbar vs. hybrid vs. menschlich. Voll automatisierbar (und schnell verrottend): API-Parameter, Typen, Config-Schema, Dependencies, Beispiele aus Tests. Hybrid: Architektur, Getting Started. Menschlich: Warum-Entscheidungen, Support-basiertes Troubleshooting.
Pipeline — CI als Doc-Wahrheit
Push auf main in src/ → OpenAPI/TypeDoc/Sphinx/json-schema-to-markdown → Beispiele aus Tests extrahieren → Bot-Commit oder PR. Pattern ist alt — Unternutzung ist das Problem.
AST-Parsing gibt Kontrolle über Extraktion (JSDoc, Parameter, @example). Für hybrid: Stubs mit TODO bei neuen Modulen, Doc-Coverage wie Code-Coverage (Schwellwert in CI), LLM-First-Draft + Human Review.
Stale-Script: Doc-mtime vs. Source-mtime — Flag ab 90 Tagen Drift trotz Code-Changes.
Vier-Wochen-Playbook für Mandate
Woche 1: Support-Fragen zählen („How do I…“, „docs say…“), Onboarding-Zeit baseline. Woche 2: Referenz in CI (OpenAPI, TypeDoc, …). Woche 3: Doc-Coverage-Gate, Start 50 %, hochdrehen. Woche 4: Stale-Detection aktivieren.
Ehrliche Grenze: Automatisierung ersetzt nicht gute Erklärungen — sie eliminiert Sync-Arbeit, damit Teams high-value Writing machen.
Rollout graduell — Vertrauen in Bot-Commits aufbauen, bevor kritische Seiten vollautomatisch laufen.
Zielbild — veraltete Docs unmöglich machen
Hört auf, Menschen zur Doc-Disziplin zu erziehen — baut Systeme, die veraltete Referenz technisch erschweren. Kombiniert mit Agent-Readiness (KI-lesbar machen) und Qualitätsgrundlagen (Warum Docs scheitern).
Review alle paar Monate: generierte Seiten stichprobenartig, Extraktion verbessern, neue Rot-Hotspots automatisieren.
Zukünftiges Ich in sechs Monaten dankt euch — und eure Agenten-Kunden auch.
