README bewerten
Überblick
Ein README ist die Eingangstür eines Repositorys. Die meisten READMEs scheitern, weil sie die Oberfläche dokumentieren (wie die API aussieht) anstatt das mentale Modell (was das System ist, wie es sich verhält, wo es bricht). Dieser Skill bewertet ein README anhand von 8 Achsen und liefert die eine beste Heuristik für das Gesamturteil.
Verwenden Sie diese Rubrik, um eine schriftliche Bewertung zu erstellen. Für jeden Abschnitt: nennen Sie, was funktioniert, was fehlt und was zu beheben ist. Seien Sie konkret – zitieren Sie Zeilen, verweisen Sie auf Überschriften, benennen Sie den Fehler.
Verwendung
- Lesen Sie das README einmal komplett durch, ohne zu bewerten – der erste Eindruck zählt.
- Gehen Sie die 8 Abschnitte unten in der Reihenfolge durch. Jeder Abschnitt enthält Fragen; beantworten Sie jede mit Belegen aus dem README.
- Wenden Sie die eine beste Heuristik am Ende als Plausibilitätsprüfung für Ihr Urteil an.
- Durchsuchen Sie das README nach den aufgeführten Anti-Patterns – diese führen zu automatischen Abzügen.
- Erstellen Sie eine Punch List: Was muss behoben werden, in der Reihenfolge der Priorität.
Die Rubrik
1. Erst-30-Sekunden-Test
Ob ein Fremder sich oberhalb der Falte orientieren kann.
- Was ist das? Ein Satz oberhalb der Falte, den ein Fremder versteht.
- Für wen ist es? Der Leser kann sich innerhalb des ersten Absatzes für oder gegen das Projekt entscheiden.
- Funktioniert es? Lebenszeichen – CI-Status, wöchentliche Downloads, letztes Veröffentlichungsdatum, Versionsabzeichen, „getestet auf X". Eine Live-Downloadzahl ist ein stärkeres Signal als ein Veröffentlichungsdatum; ein grünes CI-Abzeichen ist stärker als beides. Niemand vertraut einem verlassenen Repository.
2. Kann ich es in unter 5 Minuten installieren?
Ob ein Leser, der jeden Codeblock der Reihe nach einfügt, am Ende ein funktionierendes System hat.
- Voraussetzungen sind explizit – Laufzeitversionen, Abhängigkeiten von Drittanbietern, externe Dienste.
- Die Installation ist ein kopierbarer Block. Kein „siehe unsere Dokumentation für die Installation".
- Quick Start läuft vollständig durch. Keine Lücken, kein „konfiguriere X" ohne Angabe wie.
- Beispiele verwenden konsistente Namen.
mainKnowledgePoolim Setup und'main'in der Suche ist der #1 README-Fehler – er bricht jeden Copy-Paste-Benutzer stillschweigend.
3. Entspricht es der Realität?
Ob das README zusammen mit dem Code gepflegt wurde.
- Jedes Codebeispiel lässt sich kompilieren. Veraltete Typsignaturen und umbenannte Exporte sind schlimmer als keine Beispiele.
- Versionsunterschiede werden benannt. Falls ein Video/Blogbeitrag/Abschnitt veraltet ist, sagen Sie es an Ort und Stelle, anstatt den Leser auf die harte Tour entdecken zu lassen.
- Fehlerantworten und Randfälle sind dokumentiert, nicht nur der Happy Path – Leser vertrauen Dokumentation, die zugibt, was kaputt geht.
4. Ist es navigierbar?
Ob jemand, der zum dritten Mal zurückkommt, schnell finden kann, was er braucht.
- Inhaltsverzeichnis für alles über ~300 Zeilen.
- Abschnittstiefe ist sinnvoll. h4 unter h3 unter h2 sollte echte Enthaltenseinsbeziehungen widerspiegeln, nicht nur „mir sind die
##ausgegangen". Verwaiste Unterabschnitte sind ein Zeichen dafür, dass das Dokument gewachsen ist, ohne umstrukturiert zu werden. - Querverweise sind Links, kein Fließtext. „Siehe oben" altert schlecht;
[Metadaten-Filterung](#metadaten-filterung-wo)überlebt Bearbeitungen. - Doppelte Informationen sind gefährlich. Wenn derselbe Endpunkt zweimal dokumentiert ist, wird eine Kopie verrotten. Wählen Sie einen kanonischen Ort.
5. Vermittelt es das mentale Modell, nicht nur die API?
Ob der Leser mit Intuition geht, nicht nur mit Syntax.
- Warum, nicht nur wie. „Bulk-Ausführungen werden nie automatisch in die Warteschlange gestellt – sie müssen manuell ausgelöst werden" sagt mir mehr als eine Signaturauflistung.
- Lebenszyklen und Invarianten werden genannt. „Nur ein Bulk-Run pro Pool gleichzeitig", „Löschen kann nicht deaktiviert werden", „die ID korreliert X mit Y" – das sind die Dinge, die Benutzer schmerzhaft entdecken, wenn sie nicht aufgeschrieben sind.
- Fehlermodi werden benannt. Ein Troubleshooting-Abschnitt ist ein Stellvertreter für „der Betreuer hat dies tatsächlich in der Produktion unterstützt".
Ausnahme für Dokumentationsseiten. Falls das Projekt eine kanonische Referenzseite oberhalb der Falte verlinkt (z. B.
zod.dev/api,nextjs.org/docs), bewerten Sie diesen Abschnitt danach, ob das README genug vermittelt, dass der Leser weiß, ob er in die Dokuseite eintauchen muss und wonach er dort suchen soll – nicht danach, ob es das vollständige mentale Modell lehrt. Die vollständige Referenz im README zu duplizieren würde gegen Abschnitt 4 verstoßen („Doppelte Informationen sind gefährlich"). Die Aufgabe des READMEs ist in diesem Fall die Brücke, nicht die Enzyklopädie.
6. Progressive Offenlegung
Ob jede Zielgruppe mit dem für sie relevanten Abschnitt aufhören kann zu lesen.
- Quick Start bringt Sie zum Laufen. Referenz hilft bei Problemen. Beispiele zeigen idiomatische Nutzung.
- Fortgeschrittene Funktionen blockieren Anfänger nicht. Bulk-API, Provider-Callbacks, benutzerdefinierte Adapter – alles verschoben hinter den minimalen Pfad zu einer funktionierenden Suche.
- Konfigurationstabellen mit Pflicht-/Optional-Spalten ermöglichen Überfliegen statt Lesen.
7. Wartungssignale
Ob das Projekt lebendig und innerhalb eines Unternehmens nutzbar aussieht.
- Changelog verlinkt. Kein Changelog = kein Signal, dass das Projekt gewartet wird.
- Lizenz angegeben. Fehlende Lizenz = in den meisten Unternehmen unbrauchbar.
- Beitragspfad ist sichtbar. Auch nur eine Zeile („eröffnen Sie zuerst ein Issue") ist besser als nichts.
- Ton passt zum Reifegrad. Ein Alpha-Projekt sollte nicht wie v3 klingen; ein stabiles Projekt sollte nicht wie ein Hackathon-Pitch klingen.
8. Ehrlich über Einschränkungen
Ob der Betreuer die Zeit des Lesers respektiert.
- Adapter-Parität, Plattformunterstützung, bekannte Lücken werden genannt, nicht in einem GitHub-Issue versteckt.
- Ein Leser, der eine Einschränkung im README findet, fühlt sich informiert; derselbe Leser, der sie nach 2 Stunden Debugging findet, fühlt sich belogen.
Die eine beste Heuristik
Wenden Sie zwei Heuristiken an, abgestimmt auf die Zielgruppe des READMEs:
Benutzervertrag: Kann ein neuer Benutzer das README kalt öffnen und eine kleine korrekte Integration bereitstellen, ohne den Quellcode zu lesen? Erforderlich für jedes README.
Beitragsvertrag: Kann ein neuer Mitwirkender das README kalt öffnen und, ohne mit dem Betreuer zu sprechen, einen kleinen korrekten Pull Request bereitstellen? Erforderlich, wenn das README der Einstiegspunkt für Mitwirkende ist. Optional, wenn eine
CONTRIBUTING.mdvom README aus verlinkt ist – in diesem Fall bewerten Sie die Contributor-Erfahrung anhand dieser Datei, nicht des READMEs.
Der Beitragsvertrag erfordert, dass das README (oder die CONTRIBUTING.md) die Architektur erklärt, nicht nur die Oberfläche. Die meisten Projekte bestehen diesen Test nicht, und das ist normalerweise der Unterschied zwischen einem Projekt, das beiläufige Beiträge bekommt, und einem, das keine bekommt.
Wenn der Benutzervertrag scheitert, hat dies Vorrang vor oberflächlicher Politur in den Abschnitten 1–7. Wenn nur der Beitragsvertrag scheitert und keine CONTRIBUTING.md verlinkt ist, ist das dennoch ein echter Mangel – markieren Sie ihn, aber lassen Sie ihn nicht über benutzerorientierte Stärken dominieren.
Anti-Patterns (automatische Abzüge)
Markieren Sie diese explizit, wenn sie gefunden werden – sie deuten auf größere Probleme hin.
| Anti-Pattern | Warum es schlecht ist |
|---|---|
| Marketingtexte, wo Referenzdokumentation sein sollte | Leser brauchen Fakten, keine Werbung |
| Screenshots von Code statt Codeblöcken | Nicht kopierbar, nicht durchsuchbar, nicht barrierefrei |
| „Siehe den Quellcode" als Dokumentation | Schiebt die Aufgabe des Betreuers auf jeden Leser |
| Emoji-getriebene Feature-Listen ohne Zuordnung zu Abschnittsüberschriften | Dekoration ohne Navigationswert |
| Abzeichen ohne Zweck – mehr als ~6, oder Abzeichen, die keinem eindeutigen Signal entsprechen (CI, Lizenz, Downloads, Version, Abdeckung, Support-Kanal) | Cargo-Cult-Qualitätssignal; 5 sinnvolle Abzeichen sind okay, 10 dekorative nicht |
| Ein „Fahrplan", der eigentlich eine Wunschliste ohne Priorität oder Zeitplan ist | Schafft Erwartungen, die das Projekt nicht erfüllen kann |
| Videos/Blogbeiträge ohne den Hinweis „aufgenommen gegen Version X“ verlinkt | Leser verschwenden Zeit mit veralteten Inhalten |
Platzhaltertexte, die an Leser ausgeliefert werden (your-repo, TODO, lorem ipsum, kaputte Ankerlinks) | Der größte Vertrauenskiller oberhalb der Falte – signalisiert, dass niemand vor der Veröffentlichung Korrektur gelesen hat |
Umgekehrte Schichtung – benötigte Hilfsfunktionen (z. B. embedQuery) werden nach dem Quick Start definiert, der sie verwendet | Copy-Paste des „minimalen Pfads" erzeugt ReferenceError; der Beispielblock ist nicht wirklich eigenständig |
| Quick Start endet bei der Konfiguration ohne einen „funktioniert es?"-Snippet | Der Leser hat keine Möglichkeit zu bestätigen, dass die Installation etwas bewirkt hat; die Dokumentation deckt die Aufnahme, aber nicht den Abruf ab |
Ausgabeformat
Bei der Bewertung eines READMEs erstellen Sie:
- Urteil – eine Zeile (z. B. „Stark bei der Installation, schwach beim mentalen Modell. Ein neuer Benutzer liefert in 10 Minuten aus; ein neuer Mitwirkender kann es nicht.")
- Abschnittsbezogene Ergebnisse – für jede der 8 Achsen, was funktioniert und was fehlt, mit Zeilen-/Überschriftenverweisen.
- Getroffene Anti-Patterns – listen Sie alle aus der obigen Tabelle auf.
- Beste-Heuristik-Antwort – ja/nein für beide Verträge (Benutzer- und Beitragsvertrag) mit Begründung. Falls
CONTRIBUTING.mdverlinkt ist, vermerken Sie, dass der Beitragstest auf diese Datei beschränkt ist. - Punch List – Korrekturen in der Reihenfolge der Priorität (höchste Auswirkung zuerst).