Dokumentation die man wirklich schreibt

≈ 1 min
management

Die schlechteste Dokumentation ist die die nicht existiert. Die zweitschlechteste ist die die veraltet ist. Gute Dokumentation ist selten weil sie Disziplin braucht, keine Intelligenz.

Was dokumentiert werden muss

Nicht alles. Nur das was ein neuer Entwickler (oder man selbst in sechs Monaten) nicht aus dem Code ablesen kann.

  • Warum dieses Architektur-Entscheidung und nicht die Alternative
  • Externe Abhängigkeiten und wie sie aufgesetzt werden
  • Nicht-offensichtliche Seiteneffekte
  • Deployment-Prozess
  • Umgebungsvariablen und deren Bedeutung

Was nicht dokumentiert werden muss: was der Code tut — das steht im Code.

README als Einstiegspunkt

# Projektname

Kurze Beschreibung was das Projekt macht und für wen.

## Voraussetzungen

- PHP 8.3+
- MariaDB 10.11+
- Redis 7+

## Setup

1. `.env.example` nach `.env` kopieren und ausfüllen
2. `php database.php` — Tabellen anlegen
3. Webserver auf `/public` zeigen lassen

## Umgebungsvariablen

| Variable         | Beschreibung                  | Beispiel              |
|------------------|-------------------------------|-----------------------|
| DB_HOST          | MySQL-Host                    | 127.0.0.1             |
| TELEGRAM_BOT_TOKEN | Bot-Token für Benachrichtigungen | 123456:ABC-DEF    |

## Architektur

Kurze Beschreibung der wichtigsten Komponenten.

Architecture Decision Records (ADR)

Für größere Entscheidungen: kurzes Dokument das festhält was entschieden wurde, warum, und welche Alternativen verworfen wurden.

# ADR-003: Sessions statt JWT für Web-Auth

**Datum:** 2025-06-01  
**Status:** Akzeptiert

**Kontext:** Authentifizierung für das Admin-Panel implementieren.

**Entscheidung:** PHP-Sessions mit Redis statt JWT-Tokens.

**Gründe:** Sessions sind serverseitig invalidierbar (wichtig für "alle Geräte abmelden"),
kein Token im localStorage (kein XSS-Risiko), kein Overhead für Token-Validierung.

**Verworfene Alternative:** JWT — macht für diesen Use Case keinen Vorteil.

Doku nah am Code halten

Wenn Dokumentation weit vom Code entfernt lebt veraltet sie schneller.

project/
  docs/
    adr/          ← Architekturentscheidungen
    runbooks/     ← Betriebsanleitungen
  README.md       ← Einstiegspunkt
  CHANGELOG.md    ← Was hat sich geändert

Das Wichtigste

Direkt nach dem Feature schreiben, nicht am Sprint-Ende.
Am Sprint-Ende ist das Wissen schon verblasst, die nächste Aufgabe drängt, die Doku bleibt leer.

Fünf Minuten nach dem Merge sind besser als zwanzig Minuten nie.