README Dateien haben in Softwareprojekten eine lange Tradition. Diese ursprünglich reinen Textdateien enthielten Lizenzinformationen und Anweisungen wie aus dem Quellcode das entsprechende Artefakt kompiliert werden konnte oder aber wichtige Hinweise zu Installation des Programms. Es gibt keinen wirklichen Standard, wie man eine solche README Datei aufbauen sollte.
Seit dem GitHub (2018 von Microsoft übernommen) als kostenfreie Code Hosting Plattform für Open Source Projekte seinen Siegeszug angetreten ist, gab es schon recht früh die Funktion, dass die README Datei als Startseite des Repositories anzuzeigen. Dazu muss lediglich eine einfache Textdatei mit der Bezeichnung README.md im Hauptverzeichnis des Repository erstellt werden.
Um die README Dateien übersichtlicher strukturieren zu können, wurde eine Möglichkeit für eine einfache Formatierung gesucht. Schnell hatte man sich für die markdown Notation entschieden, da diese einfach zu nutzen ist und auch recht performant gerendert werden kann. Somit sind die Übersichtsseiten besser für Menschen zu lesen und können als Projektdokumentation genutzt werden.
Es ist möglich, mehrere solcher markdown Dateien als Projektdokumentation miteinander zu verknüpfen. Somit erhält man eine Art Mini WIKI das im Projekt enthalten ist und außerdem auch über Git versioniert wird.
Das Ganze wurde so erfolgreich, das Selfhosting-Lösungen wie GitLab oder das kommerzielle BitBucket diese Funktion ebenfalls übernommen haben.
Nun stellt sich aber die Frage welche Inhalte man am besten in solch eine README Datei schreibt, damit diese für Außenstehende auch einen wirklichen Mehrwert darstellen. Dabei haben sich im Laufe der Zeit folgende Punkte etabliert:
- Kurzbeschreibung des Projekts
- Bedingungen, unter denen der Quellcode verwendet werden darf (Lizenz)
- Wie ist das Projekt zu verwenden (z.B. Anweisungen zum Compilieren oder wie wird die Bibliothek in eigene Projekte eingebunden)
- Wer sind die Autoren des Projekts und wie kann man sie erreichen
- Was ist zu tun wenn man das Projekt unterstützen möchte
Mittlerweile sind sogenannte Badges (Sticker) sehr populär. Diese referenzieren oft auf externe Dienste, wie beispielsweise der freie Continuous Integration Server TravisCI. Diese helfen Ausstehenden, die Qualität des Projekts zu beurteilen.
Auf GitHub gibt es auch diverse Vorlagen für README Dateien. Man muss allerdings auch ein wenig auf die tatsächlichen Gegebenheiten des eigenen Projekts schauen und beurteilen, welche Informationen für Nutzer bzw. Anwender wirklich relevant sind. Solche Vorlagen helfen aber sehr dabei, herauszufinden, ob man möglicherweise einen Punkt übersehen hat.
Da mittlerweile ziemlich jeder Hersteller von Source Control Management Serverlösungen die Funktion die README.md Datei als Projektstartseite für das Code Repository anzuzeigen integriert hat, bedeutet das eine README.me auch für kommerzielle Projekte eine sinnvolle Sache sind.
Auch wenn die Syntax für markdown leicht zu erlernen ist, kann es bei umfangreichen Editierungen solcher Dateien durchaus komfortabler sein, direkt einen MARKDOWN Editor zu nutzen. Dabei sollte man darauf achten, dass die Vorschau auch korrekt dargestellt wird und nicht nur ein einfaches Syntaxhighligting angeboten wird.
Auf alle Fälle lohnt sich ein Blick auf die GitHub Seite https://www.readme-templates.com zu werfen. Weitere Ressourcen zum Thema finden sich hier: