menu_book GitHub-README-Generator star

Wie ein gutes README entsteht

Ein README, das Besuchern wirklich hilft, folgt einer Form, die GitHub-Nutzer längst kennen, weil tausende gut gepflegte Repositories dasselbe Grundgerüst verwenden: oben ein Titel mit einzeiliger Beschreibung, eine etwas längere Zusammenfassung dessen, was das Projekt tut und warum, eine Funktionsliste, Schritt-für-Schritt-Installationsanweisungen (die genauen Befehle, keine Fließtext-Erklärung), ein Nutzungsbeispiel mit echter Ein- und Ausgabe, ein kurzer Hinweis zum Mitwirken und schließlich die Lizenz. Dieses Tool rät diese Form nicht — es setzt sie durch. Jedes ausgefüllte Feld wird genau einem dieser Abschnitte zugeordnet, in der Reihenfolge, die GitHub-Besucher erwarten, sodass die erzeugte Datei wie das README eines etablierten Open-Source-Projekts wirkt, selbst wenn es Ihr erstes ist.

Konkretes Beispiel: Geben Sie "flask" als Projektname, "MIT" als Lizenz und pip install flask als Installationsbefehl ein. Der Generator schreibt einen eingezäunten ```bash-Block mit genau diesem Befehl unter einer Installation-Überschrift und platziert daneben ein passendes shields.io-Badge — ![License](https://img.shields.io/badge/license-MIT-blue) — neben dem Titel. Nichts wird erfunden; Badge-Text und Installationsbefehl sind genau das, was Sie eingegeben haben, nur in die richtige Markdown-Syntax eingebettet.

Auch die Reihenfolge der Abschnitte ist nicht willkürlich — sie folgt dem tatsächlichen Weg, den ein Leser durch ein neues Projekt nimmt. Die Installation kommt vor der Nutzung, weil niemand Ihr Beispiel ausprobieren kann, bevor das Paket auf seinem Rechner ist; Mitwirken und Lizenz stehen am Ende, weil sie vor allem für die kleinere Gruppe von Besuchern wichtig sind, die sich bereits entschieden haben zu bleiben. Genau zu dieser Reihenfolge kommen Maintainer großer, bekannter Repositories unabhängig voneinander — deshalb wirkt ein so aufgebautes README sofort vertraut statt improvisiert. Und weil sich die Vorschau beim Tippen aktualisiert, sehen Sie die Wirkung jedes Feldes sofort, statt das Formular blind auszufüllen und zu hoffen, dass das Ergebnis am Ende gut lesbar ist.

Was Sie wissen sollten

• Badges sind live, keine statischen Bilder. Jedes Badge ist eine Anfrage an einen Drittanbieter-Dienst — meist shields.io —, der spontan ein SVG erzeugt. Ein Build-Status- oder Versions-Badge fragt die zugrunde liegenden Daten jedes Mal neu ab, wenn jemand Ihr README auf GitHub lädt; es ist kein Bild, das Sie einmal erzeugen und dann vergessen.
• Das Lizenz-Badge braucht kein Konto. Es wird aus einem öffentlichen URL-Muster mit dem von Ihnen gewählten Lizenznamen erzeugt — kein API-Schlüssel, keine Anmeldung, kein Ratenlimit, um das sich ein Einzelmaintainer sorgen müsste.
• Das ist eine Vorlagen-Engine, kein Schreiber. Sie erfindet niemals Funktionsbeschreibungen, Installationsschritte oder Nutzungstext — alles in der Ausgabe ist Text, den Sie selbst eingegeben haben, lediglich neu formatiert in standardmäßige Markdown-Überschriften, eingezäunte Codeblöcke und Badge-Syntax.
• Die Ausgabe ist reines, editierbares Markdown. Fügen Sie sie in README.md ein und bearbeiten Sie danach von Hand weiter — nach dem Kopieren des Ergebnisses bindet Sie nichts an die Struktur des Generators.
• Das Formular dient zugleich als Checkliste. Leere Felder bei "Nutzungsbeispiel" oder "Mitwirken" zu sehen, ist selbst schon ein nützlicher Hinweis — eine schnelle Erinnerung an die Abschnitte, die echte Maintainer ausfüllen sollten, noch bevor Sie eine Zeile Dokumentation geschrieben haben.