README schreiben — Praxis-Anleitung für GitHub

Warum das README das wichtigste Dokument ist

GitHub zeigt das README.md automatisch auf der Repo-Seite. Wer dein Projekt findet, sieht zuerst das README — nicht den Code, nicht die Docs, nicht die Tests. Das README entscheidet, ob jemand bleibt oder weitergeht.

Konkret: zehn Sekunden hat ein neuer Besucher um zu entscheiden ob dein Projekt für ihn relevant ist. In diesen zehn Sekunden muss er verstehen können: was das Projekt macht, wer es nutzt, wie er anfaengt. Wenn diese Info nicht in den ersten paar Bildschirm-Pixeln steht, verliert er Interesse.

Die Standard-README-Struktur (in dieser Reihenfolge)

Erstens: Projekt-Name als H1 und ein-Satz-Beschreibung. Was macht das Projekt? Für wen? Diese Frage muss in der ersten Zeile beantwortet sein.

Zweitens: Status-Badges. Build-Status, Test-Coverage, NPM-Version, Lizenz. Visuell sofort sichtbar.

Drittens: Quick-Start. Drei Befehle, die das Tool installieren und starten. Wenn Quick-Start mehr als drei Befehle braucht, ist die UX zu komplex.

Viertens: Features oder Anwendungsfälle als Liste. Was kann das Tool? Wofür ist es geeignet?

Fünftens: Vollständige Installation und Konfiguration. Details für Power-User.

Sechstens: Beispiele und Screenshots. Bilder sagen mehr als Worte.

Siebtens: Kontribution, Lizenz, Kontakt.

1. Projekt-Name + Ein-Satz-Beschreibung (H1)
2. Status-Badges (Build, Tests, NPM-Version, Lizenz)
3. Quick-Start: 3 Befehle zum Loslegen
4. Features oder Anwendungsfälle
5. Detail-Installation und Konfiguration
6. Beispiele und Screenshots
7. Kontribution, Lizenz, Kontakt

Badges richtig einsetzen

Badges sind die kleinen Status-Symbole oben im README. Sie zeigen automatisch generierte Informationen wie Build-Status oder NPM-Version. Praktisch, weil sie immer aktuell sind.

Wichtigste Quellen: shields.io für generische Badges, GitHub-Actions für Build-Status, codecov.io für Test-Coverage, npmjs.com für NPM-Versions. Alle haben URL-Patterns, die du direkt als Markdown-Image einbettest.

Vermeide Badge-Overkill: vier bis sechs Badges sind genug. Mehr wirkt unruhig und keine wird mehr ernst genommen.

Quick-Start: die wichtigste Sektion

Der Quick-Start ist das Herz jedes README. In drei bis fünf Code-Blöcken muss klar werden: wie installiere ich das Tool, wie starte ich es, wie sehe ich das erste Ergebnis.

Best Practice: schreibe Quick-Start als ob du ihn einem Anfaenger zeigst. Keine Annahmen über Vorwissen. Wenn dein Tool Node.js braucht, schreib das. Wenn ein Datenbank-Setup nötig ist, verlink auf die Anleitung.

Code-Blöcke mit Sprache markieren: ` ```bash` für Shell-Befehle, ` ```javascript` für JS-Snippets. Das aktiviert Syntax-Highlighting auf GitHub.

Screenshots und Demos einbinden

Bilder sind in READMEs unterbewertet. Ein Screenshot vom UI sagt mehr über dein Tool als drei Paragraphen Beschreibung. Animierte GIFs (mit Tools wie Kap oder LICEcap) zeigen Workflows.

Speichere Bilder im Repo unter `docs/images/` oder `assets/`. Verlink sie relativ: ``. GitHub rendert sie inline.

Datei-Größe beachten: PNGs werden auf GitHub direkt geladen. Wenn dein Screenshot 5 MB ist, laden mobile Nutzer langsam. Optimiere mit Tools wie squoosh.app oder ImageOptim — meist kannst du 70% Größe sparen ohne sichtbare Qualitäts-Einbusse.

Lizenz und Kontribution

Lizenz-Sektion ist Pflicht für Open-Source-Projekte. MIT, Apache-2.0 oder GPL sind die häufigsten. Nutze choosealicense.com um die richtige für dein Projekt zu finden.

Kontribution-Sektion sollte erklären: wie kann jemand beitragen? Issue-Templates? PR-Vorgehen? Code-of-Conduct? Bei kleineren Projekten reicht ein Satz wie "PRs willkommen, bitte vorher Issue öffnen". Bei größeren brauchst du ein CONTRIBUTING.md.

Kontakt: GitHub-Issues sind Standard. Email-Adresse optional, aber empfohlen für Security-Reports.

Template, das du direkt anpassen kannst

Hier ein Markdown-Template für dein README. Anpassen, fertig.

Häufige Fehler

Erstens: zu lang. README mit 2000 Zeilen liest niemand. Detail in separate Doku-Dateien auslagern.

Zweitens: keine Screenshots. Visuelle Beweise, dass dein Tool funktioniert, sind überzeugender als Beschreibung.

Drittens: veralteter Quick-Start. Wenn die Installation sich ändert, muss das README sofort mit. Sonst frustrierst du neue User.

Viertens: fehlende Lizenz. Ohne Lizenz ist Code per Default urheberrechtlich geschützt, also nicht wiederverwendbar. Selbst wenn du Open-Source willst, musst du eine Lizenz angeben.

Häufige Fragen