Was macht README-Schreiber?
Ein README hat eine Aufgabe: einen Besucher von „Was ist das?“ zu einem funktionierenden ersten Befehl in unter einer Minute zu bringen und ihm dann zu zeigen, wie er weitermachen und wie er helfen kann.
Verwendungszweck
- Ein README für ein neues Projekt schreiben oder ein dünnes oder weitschweifiges umschreiben
- Ein README vor einer Veröffentlichung oder einem 1.0-Release überprüfen
- Der Nutzer sagt, das Projekt wird besucht, bekommt aber keine Sterne, Installationen oder Mitwirkende
Wann nicht verwenden
- API-Referenzdokumentation (aus dem Code generieren; vom README aus verlinken)
- Lange Tutorials oder Architekturdokumente: in
docs/ablegen und verlinken
Arbeitsablauf
-
Fakten vor dem Schreiben sammeln. Das Manifest (
pyproject.toml,package.json,composer.json,Cargo.toml...), die CLI--helpoder den Haupteinstiegspunkt, vorhandene Dokumente und die Lizenz lesen. Den echten Installationsbefehl und ein echtes Beispiel finden. Niemals Flags, Ausgaben, Benchmarks oder Funktionen erfinden. -
Den Nutzer nur fragen, was der Code nicht verraten kann: für wen das Projekt ist, das eine Problem, das es löst, und warum es besser ist als die offensichtliche Alternative. Wenn sie nicht verfügbar sind, einen neutralen Pitch aus dem Code schreiben und zur Überprüfung markieren.
-
Das aktuelle README linten (falls vorhanden).
scripts/ist relativ zu diesem Skill:python3 scripts/readme_lint.py README.md python3 scripts/readme_lint.py README.md --json --strict -
Mit der Struktur aus structure.md schreiben, beginnend mit der Vorlage. Die Reihenfolge ist wichtig: Titel + Badges, Pitch, (Demo-Bild), Schnellstart, Funktionen, Nutzung/Beispiele, Konfiguration, FAQ, Roadmap, Mitwirkende, Lizenz.
-
Die Schreibregeln anwenden:
- Pitch: ein Satz, unter 200 Zeichen, keine Übertreibungen. Muster:
„
<name>ist ein(e)<Kategorie>, die<macht X>für<Zielgruppe>,<Hauptunterscheidungsmerkmal>.“ - Erster Codeblock vor Zeile 60. Jeder Befehl muss kopierbar und echt sein.
- Ausgabe nach Befehlen zeigen, wo es hilft (
# => ...oder ein separater Block). - Tabellen für Optionen und Vergleiche verwenden, Listen für Funktionen (zuerst den Nutzen nennen).
- Verlinken, nicht einfügen: lange Dokumente, Änderungsprotokolle und API-Referenzen gehören woanders hin.
- Jedes Bild erhält Alternativtext; SVG oder kurzes GIF des Hauptablaufs bevorzugen.
- Pitch: ein Satz, unter 200 Zeichen, keine Übertreibungen. Muster:
„
-
Badges. Nur Badges verwenden, die wahr und gepflegt sind, in dieser Reihenfolge: CI-Status, aktuelle Version (PyPI/npm/Packagist/Release), Downloads (optional), Lizenz. Beispiele in structure.md.
-
Erneut linten, bis keine Fehler mehr vorhanden sind. Warnungen beheben oder dem Nutzer erklären, warum nicht.
-
Die Links überprüfen, die der Linter nicht prüft: absolute URLs und Anker. Klicktest oder erklären, welche nicht verifiziert wurden.
Ausgabe
- Die neue oder aktualisierte
README.md(bei Umschreibungen eine Diff-Zusammenfassung zeigen). - Das endgültige Lint-Ergebnis.
- Eine kurze Liste von Fakten, die nicht verifiziert werden konnten, und Platzhaltern, die der Nutzer ausfüllen muss (Demo-GIF, Screenshots, Benchmark-Zahlen).
Lint-Regeln
| Regel | Stufe | Bedeutung |
|---|---|---|
| title | Fehler/Warnung | genau eine H1 |
| pitch | Fehler/Warnung | ein kurzer erster Absatz unter dem Titel |
| badges | Warnung | kein Badge gefunden |
| install | Fehler/Warnung | Abschnitt zur Installation (oder Schnellstart), mit einem Codeblock |
| quickstart | Fehler/Warnung | Abschnitt zur Nutzung, Schnellstart oder Beispiel, mit Code |
| code | Fehler | überhaupt kein Codeblock |
| scroll | Warnung | erster Codeblock nach --max-scroll Zeilen (Standard 60) |
| contributing, license | Warnung | fehlender Abschnitt |
| faq, toc | Info | empfohlen |
| alt-text | Warnung | Bild ohne Alternativtext |
| broken-link | Fehler | relativer Link zu einer fehlenden Datei oder ein leerer Link |
| broken-anchor | Fehler | #anker-Link (Inhaltsverzeichnis), der auf keine Überschrift oder kein id/name-Attribut im HTML verweist, unter Verwendung der GitHub-Slug-Regeln |
| placeholder | Warnung | TODO, TBD oder Lorem Ipsum hinterlassen |
Exit 1 bei Fehlern (und bei Warnungen mit --strict).