Warum klassische Doc-Generatoren scheitern
Der naheliegende Ansatz — Code parsen, Metadaten extrahieren, Template füllen — liefert Signaturen mit Extra-Schritten, aber keine Hilfe bei Wann, Warum und Was passiert bei null. Kommentare rotieren schneller als Code; Docstrings sind Hinweise, keine Wahrheit.
Die Einsicht für Berater und Agenturen: Gute Auto-Docs entstehen aus Code-Änderungen, nicht aus Code-Snapshots. Dokumentation ist ein Diff, kein Foto des gesamten Repos.
Steve Baka: Beim Kunden nach Change-getriebener Generierung fragen — nicht nach „noch einem Sphinx-Setup“.
Change-getriebene Architektur
Pipeline: Git-Change → semantischer Diff (AST, z. B. tree-sitter) → Kontext (bestehende Docs, Style Guide) → Doc-Delta → Merge mit Preserve-Markern → Deploy.
Beispiel: Neuer Query-Parameter include_items — schlechter Generator listet Felder; guter Generator markiert „Neu in v2.3“, zeigt erweiterte JSON-Response, schreibt Changelog-Eintrag.
LLM-Aufgabe: Bestehende Doc-Section updaten, nicht von Null schreiben — engere Constraints, bessere Trefferquote.
Schichten, die Agenturen beim Kunden brauchen
Change Detection: Git-Diff reicht nicht — semantische Einheiten (neuer Parameter, Breaking Signature). Documentation Context: vorhandene Seiten, Beziehungen zu anderen APIs, Voice/Tabellen-Format.
Generation Engine: Prompt = Change + Existing + Style Guide → Delta. Merge & Deploy: <!-- auto --> vs. <!-- human -->; Breaking Changes → Migration-Block mit Vorher/Nachher-Code.
Config-Muster: sources (was dokumentieren), ignore (Tests, intern), preserve (Philosophie, About), require_review (Tutorials), auto_deploy (API-Referenz).
Harte Lektionen für Angebote
1. Signaturen > Kommentare als Wahrheit. 2. Weniger generieren — nur public API, nicht jede Helper-Funktion (400 Seiten Rauschen). 3. Breaking Changes automatisch mit Deprecation + Migration. 4. Beispiele brauchen Human Review — Referenz ok, Beispiele mittelmäßig. 5. Escape Hatches pro Section.
80/20: ~65 % Doc-Volumen (Referenz, Config, Changelog) automatisierbar; ~35 % (Tutorials, Architektur, Getting Started) menschlich.
Minimum Viable Stack: CI-Trigger bei Merge, Parser, semantischer Diff, LLM, Merge-Logik, Deploy — Wochen bis MVP, Monate bis Qualität.
Checkliste vor Kunden-Pitch
□ Versteht das Tool semantische Changes? □ Preserve human sections? □ Git-Workflow (PR vs. auto-deploy)? □ Scope auf public API? □ Breaking-Change-Pfad?
Kernbotschaft: Dokumentation als Build-Artefakt — gleicher Trigger wie Code — nicht separates Nachziehen.
Verknüpfung: KI-Docs Sechs Monate, Docs-Automation-Tools.
