Schlechte Dev-Docs sind ein Anreizproblem
Die meiste Developer-Dokumentation ist nicht „mittelmäßig“ — sie kostet Stunden, zerstört Vertrauen und treibt Support. Ursache selten fehlendes Schreibtalent: Niemand wird befördert für großartige Docs. Wer Code am besten kennt, erklärt am schlechtesten (Curse of Knowledge). Docs verrotten schneller als Milch — ohne Wartungsbudget.
Steve Baka sieht in Agentur-Mandaten oft dieselben vier Muster — plus jetzt ein fünftes: Agenten können HTML-Docs nicht zuverlässig lesen, wenn KI-Lesbarkeit fehlt.
Kurzliste typischer Fehler: veraltete Beispiele, zu viel Jargon, Marketing statt Technik, Kitchen-Sink-Navigation, fehlende Markdown-Pfade.
Die vier Reiter — und was stattdessen hilft
Archäologie: Deprecated APIs, alte Screenshots — ein Treffer, und Entwickler lesen nur noch Source. Fix: Generierung aus Code + Stale-Detection.
Expert Blindness: Interne Begriffe ohne Kontext. Fix: Review durch jemanden ohne Code-Kontext; 30-Sekunden-Regel auf jeder Seite.
Marketing-Infektion: „Revolutionär“ vor der Antwort. Fix: Technische Antwort zuerst — Developer riechen Investor-Copy sofort.
Kitchen Sink: Alles dokumentiert, nichts findbar. Fix: Task-orientierte IA — „Auth hinzufügen“, nicht „Auth Module“.
Techniken, die messbar wirken
User-Problem vor Architektur — Getting Started in 5 Minuten, dann Auth, Daten, Fehler, Deploy.
Code vor Erklärung — Pattern Matcher sehen funktionierendes Beispiel schneller als Prosa.
Fehler first-class — jede Fehlermeldung durchsuchbar mit Ursache, Fix, Fallback.
Kollegen-Ton — „du/wir“, Rough Edges zugeben, kein „Welcome to our documentation!“
Progressive Disclosure: Einstieg minimal, Referenz verlinkt — Diataxis locker anwenden (Tutorial vs. Reference nicht mischen).
Frische — drei Hebel für Agenturen
1. Aus Quellcode generieren — Signaturen, OpenAPI, Typen. Mensch schreibt Warum, Maschine liefert Was.
2. Oberfläche radikal reduzieren — jede Seite ist Wartungsschuld; Edge-Cases verlinken statt duplizieren.
3. Änderungen erkennen — Alerts wenn dokumentierte Pfade im PR diff landen; CI-Hinweis „Doc-Update nötig“.
Verknüpfung: Dokumentations-Rot stoppen und Veraltete Docs vermeiden.
Checkliste für neue Doc-Seiten
1. Welches User-Problem? 2. Prerequisites verlinkt? 3. Minimales funktionierendes Beispiel? 4. Typische Fehler? 5. Nächste Schritte? 6. Automatisierbarer Teil? 7. Ehrlich über Komplexität?
Start klein: ein bulletproof Getting-Started — jeder Befehl copy-paste, jeder Fehler erklärt. Dann ausbauen.
Großartige Docs sind teuer — aber schlechte Docs sind teurer (Support, Churn, langsames Onboarding). Für KI-Beratung: Docs-Qualität ist Teil der Agent-Readiness-Story.
