Gute PRs und READMEs schreiben

Warum technisches Schreiben wichtig ist

In Code Reviews ist Ihre PR-Beschreibung der Einstiegspunkt fuer den Reviewer. Eine gute PR-Beschreibung kann:

Den Reviewer schnell verstehen lassen, was Sie getan haben
Rueckfragen reduzieren
Zeigen, dass Sie gruendlich nachgedacht haben
3 Monate spaeter beim Durchsehen der Historie Zeit sparen

Standardstruktur der PR-Beschreibung: What/Why/How/Testing

1. What (Was wurde gemacht)

Knappe Zusammenfassung in einem Satz.

Refactor authentication flow to support OAuth2 and magic link sign-up

Schluesselausdruecke:

Add X — Neue Funktion hinzugefuegt
Fix X — Bug behoben
Refactor X — Code umgeschrieben (ohne Funktionsaenderung)
Optimize X — Leistung verbessert
Implement X — Design umgesetzt

2. Why (Warum)

Der am haeufigsten vergessene Teil. Erklaeren Sie Hintergrund und Motivation.

Why:
- Users requested passwordless sign-up option
- Current session-based auth doesn't scale to multiple domains
- OAuth2 is industry standard for enterprise integrations

3. How (Wie)

Ueberblick ueber die technische Implementierung auf hoher Ebene.

How:
1. Created JWT service using Web Crypto API for signing/verification
2. Replaced SessionMiddleware with AuthMiddleware that validates JWT
3. Added OAuth2 routes for Google/GitHub sign-in

Breaking changes:
- Clients now need to store and send JWT in Authorization header

Schluesselausdruecke:

Created X using Y — Technologieauswahl
Replaced X with Y — Migration
Breaking changes — Nicht rueckwaertskompatible Aenderungen

4. Testing (Wie getestet)

Testing:
- Manual testing: Verified OAuth2 sign-in with Google and GitHub accounts
- Existing auth tests pass (147 tests)
- Added 23 new tests for JWT and OAuth2 flows
- Load tested with 1000 concurrent requests (no issues)

Grammatikfallen beim technischen Schreiben

1. Tempus (haeufigster Fehler)

Prinzip: Praesens fuer was der Code tut, Vergangenheit fuer was Sie geaendert haben

Fehler	Korrekt
”The function was created to handle X"	"The function handles X"
"The code will validate input"	"The code validates input”

2. Artikel (haeufiger Fehler von Nicht-Muttersprachlern)

Prinzip: Erste Erwaehnung “a/an”, danach “the”; oder Plural verwenden, um Artikel zu vermeiden

Fehler	Korrekt
”We refactored authentication flow"	"We refactored the authentication flow”

3. Uebermaessiges Passiv

Prinzip: Englisch bevorzugt Aktiv. Verwenden Sie Passiv nur, wenn unklar bleiben soll, wer gehandelt hat

Passiv	Aktiv (besser)
“The JWT is generated by the server"	"The server generates the JWT"
"Breaking changes were introduced"	"This PR introduces breaking changes”

4. Feine Unterschiede bei Synonymen

Wort	Verwendung
Add	Voellig neue Funktion: “Add OAuth2 support”
Implement	Bekanntes Design umsetzen: “Implement the design from #123”
Refactor	Bestehenden Code verbessern, ohne Funktion zu aendern
Fix	Bug beheben: “Fix race condition in cache”

PR-Beschreibung: Schnell-Checkliste

What-Teil erklaert die Aenderung klar
Why-Teil hat geschaeftliche oder technische Begruendung
How-Teil beschreibt das High-Level-Design
Testing-Teil dokumentiert die Testabdeckung
Kein uebermaessiges Passiv
Artikel korrekt verwendet (“the” vs “a”)
Tempus konsistent
Links zu verwandten Issues (falls vorhanden)

README: Schnell-Checkliste

Erster Satz erklaert klar, was das Projekt ist
Demo oder Screenshot vorhanden
Installationsschritte klar und reproduzierbar
Verwendungsbeispiele direkt kopierbar
Contributing-Leitfaden (falls externe Beitraege erwuenscht)
Lizenz angegeben
Sprache praegnant (nicht zu akademisch oder zu locker)