Ein System, welches eine gute README hat, macht in aller Regel schon beim ersten Kontakt einen guten Eindruck. Wer vor dem Entwickeln eine README-Datei erstellt, hat mit wenig Aufwand ein wertvolles anwenderorientiertes Design-Dokument erstellt, welches ihn durch den gesamten Entwicklungsprozess leiten wird.
Eine README-Datei sollte enthalten:
- Eine kurze Beschreibung was das System kann (und vielleicht auch was es bewusst nicht kann).
- Die minimal notwendige Vorgehensweise zur Installation.
- Die wichtigsten Konfigurationsoptionen.
- Die vollständigen Schritte zu einem ersten Erfolgserlebnis, also eine Art „Hallo-Welt“-Tutorial, und danach ein einfaches Tutorial zu einem typischen Use-Case, das die im Vordergrund stehenden API- oder Anwendungs-Fähigkeiten auf den Punkt bringt. Je nach Umfang dieses Tutorials kann es auch außerhalb der README-Datei abgelegt werden, sollte am besten aber direkt nach dem „Hallo-Welt“-Tutorial referenziert werden.
- Weitere Punkte, die oft Stolpersteine sein könnten, sozusagen die Top5-Punkte einer FAQ.
- Referenzen auf die wichtigsten Abschnitte in einer weiterführenden Dokumentation.
Wenn man nun dieses Punkte zu allererst, also noch vor dem Entwickeln, beschreibt, ergeben sich eine viele Vorteile:
Man denkt über das System aus Endnutzersicht nach, und zwar in den wichtigsten Aspekten Umfang/Ziel, Installation, Konfiguration, Erstkontakt durch neue Benutzern und je nach Art des Systems über die API/DSL oder die Anwendung/Benutzerführung.
Man kann die Inhalte der README so beschreiben wie man sie später gerne haben will und wie man sie bei fremder Software auch am liebsten haben möchte, ohne Rücksicht auf schon vorhandenen, eventuell „entgleisten“, Code nehmen zu müssen. Der springende Punkt an der ganzen Sache ist dabei, dass sich der künftig entstehende Code viel mehr den in der README hinterlegten Gegebenheiten anlehnt und man als Entwickler die ganze restliche Zeit über eine Leitlinie vor Augen hat.
Dieses Prinzip ist nicht revolutionär: Man könnte es auch z.B. auch als Design Driven Development bezeichnen, denn am Anfang steht ein Designdokument, welches das Endergebnis beschreibt. Der entscheidende Unterschied ist aber, dass das „README-Format“ eine über jahrzehnte gewachsene pragmatische Struktur oder Form hat und dabei so minimal ist, dass es auch tatsächlich in kurzer Zeit erfasst werden kann – völlig anders als 150-seitige Design-Dokumente.
In jedem iterativ-inkrementellen Prozess ändern sich die entstandenen Artefakte und passen sich neuen Gegebenheiten und Erfarhungen an. Natürlich auch die README-Datei. Es geht nicht darum, zu Beginn etwas in Stein zu meiseln, sondern nur darum, von Beginn an aus Sicht der späteren Benutzer über das System nachzudenken. Der Aufbau einer README leitet hier den LessCoder auf einem einfachen und pragmatischen Weg durch diese ersten Schritte.
Die meisten populären Projekte z.B. auf github haben READMEs, an denen man sich vom Aufbau her orientieren kann.
(Disclaimer: Die Idee dafür kommt von diesem Blogposting)
