Dokumentations-Review

Das Problem

Dokumentation veraltet schneller als Code. Eine vor 6 Monaten geschriebene README referenziert Installationsschritte fuer einen Paketmanager, den das Team aufgegeben hat. API-Docs zeigen Parameter, die umbenannt wurden. Codebeispiele verwenden veraltete Methoden. Veraltete Dokumentation ist schlimmer als keine — sie verschwendet Stunden, wenn Entwickler Anweisungen folgen, die zu Fehlern fuehren.

Der Prompt

Pruefe die folgende Dokumentation auf Genauigkeit und Vollstaendigkeit. Handle als neuer Entwickler, der dieses Projekt nie gesehen hat und jede Anweisung woertlich befolgt.

DOKUMENTATIONSTYP: [README / API-Referenz / Onboarding-Guide / Architektur-Docs]
PROJEKT: [Kurzbeschreibung des Projekts]

DOKUMENTATION:
[Dokumentationsinhalt einfuegen]

QUELLCODE (zur Verifizierung):
[Relevanten Code einfuegen, den die Docs beschreiben]

Bewerte in diesen Dimensionen:

1. **Genauigkeit**
   - Kompilieren und laufen Codebeispiele ohne Aenderungen?
   - Stimmen API-Beschreibungen mit den tatsaechlichen Funktionssignaturen ueberein?
   - Sind Installationsschritte aktuell?

2. **Vollstaendigkeit**
   - Kann ein neuer Entwickler allein mit dieser Doku von Null zum laufenden Projekt gelangen?
   - Sind Voraussetzungen gelistet (Node-Version, Systemabhaengigkeiten)?
   - Sind Fehlerszenarien dokumentiert ("wenn Fehler X erscheint, mache Y")?
   - Sind alle oeffentlichen APIs dokumentiert?

3. **Organisation**
   - Gibt es eine klare Struktur (Quick Start → Detailguides → API-Referenz)?
   - Sind Ueberschriften aussagekraeftig und scannbar?

4. **Codebeispiele**
   - Hat jede API-Methode mindestens ein Nutzungsbeispiel?
   - Sind Beispiele copy-pasteable (vollstaendig, keine Fragmente)?
   - Sind Beispielausgaben/-Responses enthalten?

5. **Wartung**
   - Gibt es einen "Zuletzt aktualisiert"-Indikator?
   - Sind veraltete Features klar markiert?

Fuer jedes Problem liefere:
- **Abschnitt**: Wo in der Doku
- **Schweregrad**: Irrefuehrend / Unvollstaendig / Veraltet / Verbesserung
- **Problem**: Was ein neuer Leser erleben wuerde
- **Fix**: Korrigierter Dokumentationstext

Beispielausgabe

## Dokumentations-Review: 5 Probleme gefunden

### Irrefuehrend: Falscher Installationsbefehl
Abschnitt: Getting Started, Schritt 2
Doku sagt: `npm install` — aber Projekt verwendet pnpm (pnpm-lock.yaml vorhanden).
Fix: `pnpm install`

### Unvollstaendig: Fehlende Umgebungseinrichtung
Abschnitt: Getting Started
Springt von "Repo klonen" zu "Dev-Server starten" — keine Erwaehnung von:
- .env.local aus .env.example erstellen
- Benoetigte API-Keys
- Datenbank-Setup
Fix: "Umgebung einrichten"-Abschnitt zwischen Klonen und Starten einfuegen.

### Veraltet: API-Beispiel nutzt veraltete Methode
Abschnitt: Authentication API
Doku zeigt: `auth.login(email, password)` — aktueller Code erfordert `auth.signIn({ email, password })`

Wann verwenden

Beim Onboarding neuer Teammitglieder, nach grossen Refactorings oder vor der Veroeffentlichung eines Open-Source-Projekts ausfuehren. Besonders wertvoll, wenn Dokumentation waehrend der initialen Entwicklung geschrieben und seitdem nicht aktualisiert wurde.

Profi-Tipps

• Quellcode einbeziehen — Dokumentationsgenauigkeit kann nur gegen die Implementierung verifiziert werden. Immer beides liefern.
• Quick Start woertlich testen — “Gehe den Setup-Guide Schritt fuer Schritt durch und markiere jede Anweisung, die fehlschlagen wuerde.”
• Aus Code generieren — “Generiere JSDoc/TSDoc-Kommentare fuer alle exportierten Funktionen, dann erstelle daraus API-Referenzdokumentation.”