Sechs Monate KI-Dokumentation — was Agenturen realistisch erwarten können
Wer KI-Dokumentation für Kunden einführt, braucht eine ehrliche Grenzziehung — nicht den Marketing-Pitch „KI schreibt alles“. Sechs Monate Praxis über mehrere Projekte (Python-Library, TypeScript-SDK, internes Tool) zeigen: KI spart bei mechanischen Docs deutlich Zeit, scheitert aber bei Lerninhalten und Architektur-Erklärungen.
Framework: Diataxis (öffnet in neuem Tab) — Tutorials, How-To, Explanation, Reference. Diese Typen brauchen unterschiedliches Wissen; genau dort trennt sich KI-Stärke von KI-Schwäche.
Steve Baka: Agenturen sollten KI-Docs als Arbeitsaufteilung verkaufen — Maschine für Referenz, Mensch für Verständnis — nicht als Vollautomatisierung.
Wo KI wirklich gut ist
API-Referenz: Signaturen, Parameter, Return Types, Raises — aus Typ-Hints und Docstrings. Grob 3 Minuten (KI) vs. 15–20 Minuten (manuell) pro Funktion; bei hunderten Endpoints skaliert das.
Changelogs: Nicht aus Commit-Messages („fix“, „wip“), sondern aus Diff + ein Satz Intent vom Entwickler. KI formuliert dann nutzbare Release Notes inkl. Breaking Changes.
Config-Dokumentation: JSON Schema oder TypeScript-Interfaces → vollständige Optionstabellen ohne Auslassungen. Konsistenz: Ein Style Guide, den KI robotisch über 50 Seiten durchzieht — Menschen verlieren das nach Seite 12.
Wo KI aktiv schadet
Tutorials: Technisch korrekt, didaktisch wertlos — Einkaufslisten statt Lernkurve. Keine Antizipation von Verwirrung, kein „das ist erwarteter Fehler“. Regel: Tutorials nie KI-first.
Architektur-Docs: „Modular für Skalierbarkeit“ — null Information. Warum Microservices, warum Postgres — das steht in Slack und Köpfen, nicht im Code.
Troubleshooting: Generisch vs. real — „ECONNREFUSED auf macOS, Firewall-Dialog hinter anderem Fenster“ kommt aus Tickets, nicht aus Modellen.
Das Warum: KI erfindet plausible, oft falsche Begründungen für Designentscheidungen.
Die gefährliche Mitte: How-To-Guides
How-Tos sehen fertig aus, sind aber subtil falsch: fehlende Voraussetzungen, Pfade die nur auf einer Maschine laufen, veraltete Schritte nach Minor-Updates. Regel: KI darf Struktur vorschlagen — Mensch muss jeden Schritt in frischer Umgebung nachgehen vor Publish.
Praktische Arbeitsteilung für Beratungsangebote: Referenz, Config, Changelog — KI generiert, Mensch prüft. How-To — KI-Entwurf, Mensch schreibt und verifiziert jeden Schritt. Tutorial, Architektur, Troubleshooting, Explanation — ausschließlich menschlich.
Umsetzung in Kundenprojekten
1. Strukturierte Inputs — Signatur + Types + Beispiel, nicht „schreib Docs“. 2. Review-Pflicht — wer es nicht verifizieren kann, shippt nicht. 3. Preserve-Marker für human Overview-Abschnitte. 4. Fehler-Log — Muster dokumentieren, Prompts kalibrieren.
Realistische Ersparnis: 30–50 % Doc-Zeit — nicht 100 %. Gesparte Zeit in Tutorials und Architektur stecken, wo Vertrauen entsteht.
Verknüpfung: Docs-Generator — was funktioniert, Docs-as-Code 2026.
