Die Velocity-Lücke — Docs lügen bereits
Typisches SaaS-Bild: Dutzende PRs in zwei Wochen, ein Bruchteil davon aktualisiert Docs. Das ist keine Faulheit, sondern Mathematik — Code bewegt sich schneller als manuelle Nachträge. PR-Checkbox „Docs aktualisiert“ hält einen Monat, dann wird abgehakt unter Deadline-Druck.
Die meisten Docs sind beim Lesen schon falsch — nicht weil jemand log, sondern weil niemand den Handoff Code→Doc in Echtzeit schafft.
Steve Baka: Für Agentur-Kunden ist das Systems Engineering, nicht „Disziplin-Workshop“.
Living Documentation — Projektion statt Parallel-Artefakt
Altes Modell: Docs in eigenem Wiki/Ordner, getrennter Prozess. Neues Modell: Docs als Projektion des Codebases — wie Binaries aus Source. Code ändert sich → Docs ändern sich, ohne dass jemand erinnert werden muss.
Pipeline grob: Git-Event → Diff parsen → betroffene Doc-Abschnitte → Kontext aus Repo → Deploy. Frühe Regex-@doc-Ansätze lieferten accurate aber nutzlose Referenz — heute zählt semantisches Verstehen (Parameter umbenannt → alle Beispiele und Erwähnungen mitziehen, unrelated Seiten nicht fluten).
Kontrolle — preserve_manual_edits
Automatisierung ohne Leitplanken erzeugt technisch korrekten Müll. Config im Repo-Root steuert: welche Pfade public API sind, welche ignoriert, welcher Branch Wahrheit ist, `preserve_manual_edits` — menschliche Abschnitte nicht bulldozern.
Hybrid sweet spot: KI/Reference für Grunt (Signaturen, Tabellen, Stale-Hinweise); Menschen für Konzept, Tutorial-Narrativ, relevante Edge Cases.
GitHub/GitLab-Integration als Event Source, nicht nur Storage: Merge triggert Update, Doc-Failures können Merge blockieren.
Was 2026 realistisch funktioniert
Heute: API-Referenz aus Code, Stale-Detection, diff-getriggerte Updates, brauchbare Git-Integration.
Besser werdend: semantische vs. syntaktische Changes, Cross-Refs, Multi-Repo-Kohärenz.
Weiter schwer: wirklich gute Tutorials, Entscheidung was dokumentiert wird, Legacy ohne Docstrings, KI-Text der nicht nach KI klingt.
Wer „Docs vollständig gelöst“ verkauft, lügt — aber Referenz-Automatisierung plus CI ist für Agentur-Delivery bereits Pflicht.
Fünf Schritte für Beratungs-Engagements
1. Gap messen — wie viele Code-PRs mit Docs-Features vs. Doc-Updates? 2. Referenz automatisieren (OpenAPI, TypeDoc, Sphinx …). 3. Detection vor Full-Gen — PR-Kommentar „vermutlich Doc-Update nötig“. 4. Tutorials/concept human halten. 5. Docs in CI — broken docs = failed build.
Teams, die 2026 gewinnen, behandeln Docs wie Infrastruktur, nicht Content-Sprint.
Doc-Schulden sind echte Schulden — Automation plus Agent-Readiness (Benchmark) tilgen sie messbar.
