Eine README-Datei soll einem neuen Leser helfen, den ersten nützlichen Schritt zu machen. Sie müssen nicht jedes Implementierungsdetail erklären, bevor sie sagen können, was das Projekt bewirkt oder ob es für sie relevant ist.

Führen Sie mit dem Ergebnis

Beschreiben Sie, was das Projekt tut, für wen es bestimmt ist und welche wichtigen Grenzen es hat. Ein konkretes Beispiel ist nützlicher als eine Liste von Adjektiven. Platzieren Sie oben einen funktionierenden Screenshot oder ein Beispielergebnis, wenn es den Zweck erläutert.

Geben Sie dann die Voraussetzungen an: Betriebssystem, Laufzeitversion und erforderliche Dienste. Unterscheiden Sie optionale Integrationen von dem, was für den Anfang erforderlich ist. Lassen Sie nicht zu, dass der Leser mitten in der Installation eine wesentliche Anforderung entdeckt.

Geben Sie einen vollständigen Weg zum Erfolg

Schreiben Sie die Einrichtungsschritte in der Reihenfolge auf, in der sie ausgeführt werden müssen. Erklären Sie, wo Befehle ausgeführt werden sollen und wie ein erfolgreiches Ergebnis aussieht. Verwenden Sie die Platzhalterkonfiguration deutlich und schließen Sie niemals echte Anmeldeinformationen in das Beispiel ein.

Testen Sie die Anweisungen an einer sauberen Kasse oder einem gleichwertigen Ausgangspunkt. Ein Befehl, der nur funktioniert, weil auf Ihrem Computer ein nicht dokumentiertes Tool installiert ist, stellt eine Dokumentationslücke dar. Behalten Sie optionale Variationen unter dem einfachsten unterstützten Pfad bei.

Machen Sie den nächsten Schritt leicht zu finden

Fügen Sie die allgemeinen Befehle zum Ausführen, Überprüfen und Aktualisieren des Projekts hinzu. Verlinken Sie auf eine ausführlichere Dokumentation, anstatt jedes Fachthema im Eröffnungsabschnitt zu platzieren. Geben Sie den unterstützten Ort zum Melden von Problemen und gegebenenfalls die Lizenz an.

Verwenden Sie MeatPad, um die README-Datei neben den Projektdateien zu bearbeiten, und überprüfen Sie dann die gerenderte Datei Markdown im Ziel. Folgen Sie den Links und überprüfen Sie die Bilder mit den tatsächlichen Pfaden des Repositorys. Wenn sich das Setup ändert, aktualisieren Sie die README-Datei mit derselben Änderung, sodass die Anweisungen für die erste Ausführung die Version beschreiben, die die Benutzer erhalten.

Quellen und Produktdetails

Beginnen Sie mit einer Notiz. MeatPad bietet Notizen, Markdown und Projektdateien einen lokalen Arbeitsbereich auf Ihrem Mac, ohne dass ein Konto erforderlich ist.

Entdecken Sie MeatPad →