Technisches Schreiben: Dokumentation, die gelesen wird

Dokumentation scheitert nicht, weil Entwickler nicht schreiben können, sondern weil sie für das falsche Publikum zum falschen Zeitpunkt geschrieben wird. Ein 2000 Wörter langes Design-Dokument, das erst nach dem Merge entsteht, ist Archäologie. Ein README, das erklärt, was ein Projekt tut, aber nicht, wie man es startet, ist Dekoration. Die Lücke zwischen Dokumentation, die existiert, und Dokumentation, die wirklich hilft, hat ausschließlich mit Timing, Struktur und Empathie für die Leserschaft zu tun.

Gute Dokumentation beantwortet eine konkrete Frage für eine konkrete Person an einem konkreten Punkt ihres Arbeitsablaufs. Alles andere ist Rauschen.

Die vier Arten von Dokumentation

Nicht jede Dokumentation erfüllt denselben Zweck. Wer ein Tutorial wie eine Referenz behandelt (oder umgekehrt), erzeugt Dokumente, die bei beiden Aufgaben scheitern.

<!-- ❌ Mixes tutorial with reference — confusing for both audiences -->
# API Guide
To use our API, first get an API key from the dashboard.
POST /api/users accepts { name: string, email: string }...
Here's a fun history of how we built the API...
 
<!-- ✅ Separate documents for separate purposes -->
# Getting Started (tutorial)
# API Reference (reference)
# Architecture Decision: REST vs GraphQL (explanation)

Wenn du dich dabei ertappst, zwischen Erklären und Auflisten hin- und herzuspringen, teile das Dokument auf. Jeder Typ hat andere Leser mit anderen Bedürfnissen.

Architecture Decision Records

ADRs sind die Dokumentation mit dem größten Hebel, die ein Engineering-Team schreiben kann. Sie halten das Warum hinter Entscheidungen fest — den Kontext, die Randbedingungen und die Alternativen, die die Codebasis geprägt haben.

# ADR-007: Use PostgreSQL for Primary Datastore
 
## Status
Accepted
 
## Context
We need a primary datastore for the user service.
Current load: ~500 writes/sec, ~5000 reads/sec.
Team has deep PostgreSQL experience. Two engineers
have DynamoDB experience.
 
## Decision
Use PostgreSQL 14 with read replicas.
 
## Alternatives Considered
- **DynamoDB**: Lower ops overhead but vendor lock-in.
  Team experience gap would slow initial development.
- **MySQL**: Similar capabilities, but our tooling and
  migration scripts assume PostgreSQL.
 
## Consequences
- Must manage connection pooling (PgBouncer)
- Read replicas add ops complexity
- Team can reuse existing migration patterns
- Avoids vendor lock-in in the data layer

Die entscheidenden Abschnitte sind Context und Alternatives Considered. Ohne Kontext können zukünftige Entwickler nicht beurteilen, ob die Entscheidung noch gültig ist. Ohne Alternativen können sie die Abwägungen nicht bewerten, wenn sich die Umstände ändern.

Effektive ADRs schreiben

// ❌ Vague context — doesn't help future decisions
interface BadADR {
  context: "We needed a database";
  decision: "We chose PostgreSQL";
  // Missing: why not alternatives? What constraints existed?
}
 
// ✅ Specific context — enables revisiting the decision
interface GoodADR {
  context: {
    loadPattern: "500 writes/sec, 5000 reads/sec";
    teamExperience: "3 senior engineers with PostgreSQL";
    constraints: ["no vendor lock-in", "ACID required"];
    timeline: "must ship in 6 weeks";
  };
  decision: "PostgreSQL 14 with read replicas";
  alternatives: Array<{
    option: string;
    pros: string[];
    cons: string[];
    reason_rejected: string;
  }>;
}

Behandle ADRs als unveränderlich. Wenn eine Entscheidung durch eine neue ersetzt wird, schreibe ein neues ADR, das auf das alte verweist. Bearbeite niemals ein bestehendes ADR nachträglich — es ist ein historisches Dokument dessen, was zu diesem Zeitpunkt bekannt war.

Eine README-Struktur, die funktioniert

Die meisten READMEs sind entweder leer oder eine Textwand. Ein gutes README beantwortet fünf Fragen in einer bestimmten Reihenfolge — und die meisten Entwickler brauchen nur die ersten drei.

# Project Name
 
One sentence: what it does and who it's for.
 
## Quick Start
 
Three commands or fewer to go from clone to running.
 
## Development
 
How to run tests, lint, and build locally.
 
## Architecture
 
High-level overview: key directories, data flow,
external dependencies.
 
## Deployment
 
How to deploy. Environment variables. Infrastructure.

# ❌ "Check the wiki for setup instructions"
# (The wiki is outdated, has broken links, and contradicts itself)
 
# ✅ Quick Start that actually works
git clone git@github.com:team/project.git
cd project
cp .env.example .env
docker compose up -d

Der Quick-Start-Abschnitt ist der wichtigste. Wenn ein neues Teammitglied es nicht schafft, in unter 10 Minuten von git clone zu einer laufenden Anwendung zu kommen, hat das README versagt.

Code-Kommentare richtig schreiben

Code-Kommentare sollten das Warum erklären, nicht das Was. Das Was zeigt der Code bereits selbst. Ein Kommentar, der den Code nur umformuliert, erzeugt Rauschen. Ein Kommentar, der die Beweggründe erklärt, wird beim Debuggen unbezahlbar.

// ❌ Restates the code — adds nothing
// Increment counter by 1
counter += 1;
 
// ✅ Explains regulatory/business context
// GDPR Article 17: must purge all PII within 30 days
// of deletion request. The grace period allows undo.
const PURGE_DELAY_DAYS = 30;
 
// ✅ Explains non-obvious technical decisions
// Using requestAnimationFrame instead of setTimeout
// because setTimeout(0) can be throttled to 4ms+ in
// background tabs (Chrome 88+), causing visible jank
// when the tab regains focus.
requestAnimationFrame(flushUpdates);

Die besten Kommentare beantworten die Frage: „Warum würde jemand das ändern, und was müsste er dafür wissen?" Wenn die Antwort lautet: „Nichts — das ist offensichtlich", dann lass den Kommentar weg.

Inline-Dokumentation in APIs

API-Dokumentation ist dem Code am nächsten, wenn sie direkt aus ihm generiert wird. JSDoc-, TypeDoc- oder OpenAPI-Annotationen sorgen dafür, dass die Dokumentation mit der Implementierung synchron bleibt.

/**
 * Creates a new user account and sends a verification email.
 *
 * @param input - User registration data
 * @returns The created user (without password hash)
 * @throws {ConflictError} If email is already registered
 * @throws {ValidationError} If input fails schema validation
 *
 * @example
 * const user = await createUser({
 *   email: 'dev@example.com',
 *   name: 'Jane Doe',
 *   password: 'securePassword123'
 * });
 */
async function createUser(input: CreateUserInput): Promise<User> {
  const existing = await db.user.findByEmail(input.email);
  if (existing) throw new ConflictError('Email already registered');
 
  const hashed = await hashPassword(input.password);
  const user = await db.user.create({ ...input, password: hashed });
 
  await emailService.sendVerification(user.email, user.verificationToken);
 
  const { password, ...safeUser } = user;
  return safeUser;
}

Die @throws-Annotationen sind besonders wertvoll — sie dokumentieren den Fehlervertrag, den Aufrufer behandeln müssen. Fehlen sie, gelangen unbehandelte Fehlertypen bis zu den Endnutzern durch.

Dokumentation lebendig halten

Dokumentation veraltet schneller als Code. Der einzige Schutz davor ist, Dokumentation zu einem festen Teil des Workflows zu machen statt zu einem nachträglichen Gedanken.

Strategien, die funktionieren:

• ADRs sind Pflicht für jede Entscheidung, die mehr als ein Team betrifft
• README-Änderungen sind Teil der PR-Checkliste bei Infrastrukturänderungen
• Generierte API-Dokumentation läuft in der CI mit — kaputte Dokumentation lässt den Build fehlschlagen
• Vierteljährliche Doku-Review: alles löschen, was falsch ist (veraltete Dokumentation ist schlimmer als gar keine)

Strategien, die scheitern:

• „Dokumentations-Sprints" — der Backlog ist unendlich groß und die Ergebnisse sind sofort wieder veraltet
• Eine separate Wiki, gepflegt von einem „Dokumentations-Champion" — ein einzelner Ausfallpunkt für alles
• Kommentare für jede einzelne Funktion vorschreiben — das erzeugt Rauschen, kein Signal

Die wichtigsten Erkenntnisse

1. Kenne deinen Dokumenttyp — Tutorials, Anleitungen, Referenzen und Erklärungen bedienen unterschiedliche Leser
2. ADRs sind die Dokumentation mit dem größten Hebel — sie halten das Warum fest, nicht nur das Was
3. READMEs brauchen einen funktionierenden Quick Start — dauert die Einrichtung länger als 10 Minuten, hat die Doku versagt
4. Kommentare erklären das Warum, nicht das Was — der Code zeigt bereits, was er tut
5. Automatisiere, was geht — generierte API-Dokumentation und CI-Checks verhindern, dass Dokumentation veraltet
6. Veraltete Dokumentation löschen — falsche Dokumentation ist schlimmer als keine Dokumentation