Dokumentation misst, ob ein Neuankömmling lernen kann, was ein Projekt ist und wie es zu benutzen ist. Undokumentierte Software externalisiert ihre Kosten auf jeden Nutzer; dokumentierte Software skaliert das Wissen ihrer Maintainer. Für eine Abhängigkeitsentscheidung ist Dokumentation zudem Evidenz von Sorgfalt — Projekte, die sich selbst erklären, sind tendenziell Projekte, die sich selbst instand halten.
- Kategorie: Engineering-Qualität (40% innerhalb der Kategorie)
- Gewicht im Gesamtindex: 8%
- Metrikschlüssel:
documentation
Wie der Wert berechnet wird
Eine gewichtete Checkliste:
| Komponente | Gewicht | Beleg |
|---|---|---|
| README | 30 | eine README-Datei im Wurzelverzeichnis des Repositorys |
| Dokumentationsverzeichnis | 25 | ein docs/-Verzeichnis (oder gleichwertig) |
| Dokumentations-/Homepage-Site | 15 | eine aus dem Repository verlinkte Dokumentations- oder Projektwebsite |
| Repository-Beschreibung | 10 | die auf GitHub gesetzte einzeilige Beschreibung |
| Topics | 10 | zugewiesene GitHub-Topics |
| Wiki | 10 | Repository-Wiki aktiviert |
Die Schichten, vom Wesentlichen zum Auffindbaren
- Das README (30) ist die Eingangstür; fehlt es, wird nichts anderes gelesen.
- Ein Docs-Verzeichnis (25) markiert Dokumentation, die über eine einzelne Datei hinausgewachsen ist — üblicherweise Anleitungen, Referenz oder Architekturnotizen.
- Eine Dokumentationssite (15) signalisiert anhaltende Investition: gerenderte, navigierbare Dokumentation für Nutzer statt für Repository-Besucher.
- Beschreibung, Topics und Wiki (zusammen 30) sind Metadaten der Auffindbarkeit: Sie entscheiden, ob das Projekt überhaupt gefunden und eingeordnet werden kann — von Menschen, von Paketindizes und zunehmend von KI-Tooling.
Das Ergebnis lesen
- Gemessen wird die Präsenz, nicht die Prosaqualität — die ehrliche Grenze externer Prüfung (siehe Signale, keine Garantien).
- Quer zu lesen mit der Community-Gesundheit: Das README überschneidet sich als gemeinsames Fundament, aber die beiden Metriken beantworten verschiedene Fragen — lässt es sich erlernen gegenüber lässt sich daran teilnehmen.
Den Wert verbessern
- Ein substanzielles README pflegen: Zweck, Installation, minimales Beispiel, weiterführende Links.
- Wachsende Dokumentation nach
docs/verschieben und als Site veröffentlichen (GitHub Pages oder ein beliebiger Generator) — die beiden Schritte zusammen tragen 40 Punkte. - Repository-Beschreibung und Topics setzen; das Wiki aktivieren, wo es zum Arbeitsablauf des Projekts passt.
Verwandt: Community-Gesundheit · Engineering-Qualität