Wie schreibe ich eine gute Git-Dokumentation

Du nutzt eine Versionskontrolle und Du möchtest Wissen festhalten oder weitergeben. Dieser Umstand allein zeigt, dass Du bereits einiges richtig machst.

In diesem Beitrag erfährst Du, wie mit einer klaren und gut strukturierten Dokumentation die Qualität eines Projekts gesteigert werden kann. Egal ob es ein kleines Hobbyprojekt oder ein internes Konzern-Repo ist. Und mit Git-Dokumentation meine ich nicht nur die README allein.

Viel Spaß beim Lesen!

Gute Zusammenfassung als Einstieg

Versuche, in einem Satz zusammenzufassen, was Dein Repository macht. Mit diesem Satz beginnt Dein Repo. Wenn Dir das nicht gelingt, ist das ein Zeichen dafür, dass Dein Fokus noch nicht klar genug ist.

Im nachfolgenden Satz stelle dann den oder die Vorteile dar, warum ausgerechnet dieses Repo für Dich oder jemanden anderen einen Mehrwert bietet. Das können auch zwei, drei Sätze oder eine kurze Liste sein. Weniger ist mehr und Klarheit schlägt immer Umfang.

Bilder, keine Werbegrafiken

Ein aussagekräftiges Bild sollte als Nächstes folgen. Erstelle immer Bilder aus der Praxis, die entweder Deine Software oder das Ergebnis zeigen. Vermeide Mockups, Konzeptzeichnungen oder gerenderte Nachbauten.

Erstelle idealerweise Bilder von Programmfenstern oder Ausgaben Deiner Software. Sollen Prozesse angedeutet werden, nutze den ganzen Desktop mit mehreren Fenstern, die z.B. von links nach rechts “gelesen” werden. Der nachfolgende Screenshot verdeutlicht einen solchen Prozess, wo es um den Dateitransfer von Webbrowser (links) über einen Jumphost bis hin zum durchgeschleiften Laufwerk einer RDP-Verbindung geht (rechts).

Perfekt ist natürlich eine animierte .webp, die langsam durch mehrere Einzelbilder führt. In meinem gnome-script-folder-tools Repository findest Du ein solches Skript zur Erstellung.¹ Ich markiere hierfür einfach eine Handvoll Screenshots und klicke einmal im Rechte-Maustasten-Kontextmenü.

Warum diese Betonung? Weil man inzwischen in Git-Repositories immer häufiger Dinge sieht, die eher nach App-Store Werbung aussehen. Große Überschriften, viel Text (im Bild!!!), Logos - das bezeichne ich als “lautes” Design. Vom eigentlichen Inhalt bleibt wenig übrig.

Zwischenüberschriften und Inhaltsverzeichnis

Schreibe Deine Texte grundsätzlich entlang einer Gliederung, die Du Dir zumindest als “roten Faden” gedanklich zurechtgelegt hast. Am Ende kommt selten das heraus, was anfangs gedacht wurde. Wenn Du aber einer Gliederung folgst, fällt es Dir leichter, Abschnitte neu zu arrangieren und jeweils in Eingangs- und Ausgangssätzen anzupassen.

Zwischenüberschriften sind dabei kein Selbstzweck. Sie sorgen schlicht dafür, dass Inhalte bereits visuell schneller erfasst werden. Gerade bei längeren README-Dateien ist das entscheidend.

Sofern keine organisatorischen Vorgaben ein Inhaltsverzeichnis vorschreiben, gilt als Faustregel: Bei mehr als acht Zwischenüberschriften lohnt es sich, eines zu erstellen. Der ideale Ort dafür ist an dritter Stelle, nach Einstieg und Bild.

Ein weiterer Vorteil liegt darin, dass nach einem Inhaltsverzeichnis die Reihenfolge der nachfolgenden Punkte flexibler gesetzt werden kann.

Logik oder Prozessablauf

Viele Git-Plattformen unterstützen Mermaid für Ablauf- und Logikdarstellungen.² Ein Diagramm ersetzt oft mehrere Seiten Text und ist dabei deutlich präziser. Diese lassen sich von Betrachtern beliebig ein- oder auszoomen. Solltest Du statische Grafikdateien brauchen, helfen diverse Zusatztools und Online-Dienste.³

Unterschiedliche Sprachversionen

Versuche neben der deutschen mindestens eine englischsprachige Übersetzung anzubieten. Eine versteckte Funktion in Codeberg und Forgejo ist die Unterstützung unterschiedlicher Sprachversionen. Wird neben der englischsprachigen README.md auch noch eine README.de.md oder README.fr.md platziert, werden bei Aufruf die Spracheinstellungen berücksichtigt und die jeweilige Datei in der richtigen Sprache angezeigt.

Software Bill of Materials (SBOM)

Eine Auflistung der von Dir genutzten Tools, Komponenten und Abhängigkeiten gehört nicht nur zum guten Ton. Es ist ein Zeichen von Respekt. Das erfolgt üblicherweise in einer SBOM⁴ und erleichtert die Herstellung einer produktiven Umgebung für andere. Gibt es harte Versionsanforderungen, dann gehören diese Informationen genau hierhin.

Alle Informationen zu Deiner Build-Umgebung und welche Plattformen oder Systeme Du testest sind willkommen. Die spätere Ausrede “auf meinem System läuft’s” ist bei Problemen die denkbar schlechteste und für andere eine wenig hilfreiche.

Ideal in diesem Zusammenhang sind Ansible-Playbooks, Copy-and-Paste-Befehle für die Kommandozeile, klare YAML-Definitionen für OCI-Container oder Hilfsskripte in Bash oder PowerShell. Beschreibe diese in der README, auch wenn sie ausschließlich nur für Dich gedacht sind.

Changelogs

Ein unterschätztes Qualitätsmerkmal sind automatisch erstellte Changelogs. Technisch sind diese unspektakulär und mit Hilfsskripten schnell erstellt. Sie machen im Grunde nichts anderes als ein git log in eine Markdown Datei umzuleiten, wahlweise mit –oneline oder –decorate.⁵ Ganz praktisch erhöhen sie aber die Übersichtlichkeit und Handhabung. Für Dich als Maintainer gibt es weniger Nachfragen. Für Nutzer bieten Changelogs eine Entscheidungsgrundlage, ob ein Update für sie relevant ist oder nicht. Das setzt natürlich bestehende und stringente Commit-Kommentare voraus.

Schau in meine Repos, wenn Du sehen möchtest, wie man die Erstellung automatisiert.⁶

Download-Übersichtsseiten

Sobald Du compilierte Binaries anbietest, wird Vertrauen zum Thema. Wichtig ist hier ein sicherer Ort zum Download, nicht mehrere. Beim Build automatisch erstellte Prüfsummen sind kein Nice-to-have, sondern Pflicht.⁷ GPG-Signaturen sind der nächste sinnvolle Schritt zur Absicherung. Sollte Deine Zielgruppe weniger technikaffin sein, erkläre, wie Deine Dateien nach einem Downloads validiert werden können.

Ähnlich wie vollautomatisch erstellte Changelogs ist eine Übersichtsseite Deiner Downloads eine “low-hanging fruit” und kann von einem Build-Skript miterledigt werden.

Lizenz

Last but not least: Achte darauf, dass die Lizenz in Deinem Repo nicht nur als Datei enthalten ist, sondern explizit in der README auch benannt bzw. verlinkt wird. Auf die Angaben der jeweiligen Git-Plattform in den Repo-Einstellungen sollte man sich besser nicht verlassen. Spätestens beim Download als ZIP-Datei oder bei einem Git-Mirror können diese Informationen verloren gehen.

No-Go’s

Zum Schluss noch ein paar Dinge, die Du vermeiden solltest:

Verlinkte oder nachgeladene 3rd-Party-Inhalte

Hart in der Dokumentation verlinkter 3rd Party Content von Ressourcen außerhalb des Repos ist ein solches No-Go. Häufig sind das Bilder, Badges oder Banner, die den Status oder Auszeichnungen auf einer Plattform signalisieren. Bedenke, dass Repos auch geklont in Offline-Umgebungen und außerhalb von Webbrowsern betrachtet werden. Versuche Dein Repo gerade bei Assets komplett zu halten.

3rd-Party-Inhalte in Skripten

Ärgerlich sind Abhängigkeiten, die z.B. in Install-Skripten mit wget oder curl aus dem Netz nachgeladen werden. Hier reagiere ich besonders empfindlich, wenn das nicht zuvor dokumentiert oder im Skript zumindest mit einer Chance zum Abbruch hingewiesen wird. Wer sowas einfach stillschweigend macht, begeht einen Vertrauensbruch. Umgekehrt, wer Skripte aus dem Netz blind startet ohne vorher geprüft zu haben, was diese machen, der handelt fahrlässig.

Generische Verzeichnisse oder Dateinamen

Vermeide Verzeichnis- und Dateibezeichnungen wie test oder new-repo und ähnliches. Selbsterklärende Dateinamen, die bei einer globalen Dateisuche auch im entsprechenden Kontext gefunden werden können, sind hilfreicher.

Verteilte Dokumentationen

Wenn Du für Dein Projekt mehr als drei längere README-Dateien brauchst, dann solltest Du Dir überlegen, ob nicht ein kleines Wiki möglicherweise besser geeignet ist. Für einen Außenstehenden ist es frustrierend, zwischen mehreren Verzeichnissen und Dateien hin und her zu springen.

Ungepflegte oder veraltete Dokumentation

Nichts ist frustrierender als Anleitungen, die veraltet sind. Gerade in Wikis und Knowledge-Datenbanken stoße ich immer wieder auf Dokumente, wo das Datum fehlt oder zumindest ein Hinweis, für welche Version etwas geschrieben ist.

Emojis

Verzichte auf den übermäßigen Einsatz von Emojis, Icons und dekorative Symbole z.B. als Listenpunkte. Sie ersetzen keinen Inhalt und bieten auch nicht mehr Übersichtlichkeit. Ein inflationärer Gebrauch wirkt eher abstoßend. Früher hat man solche Texte nach dem gleichnamigen Truetype-Font “Wingdings” benannt und meinte damit letztlich überflüssigen Quatsch.⁸

Opensource auf Microsoft GitHub

Freie Software ist immer politisch.⁹ Seit Microsoft GitHub 2018 übernommen hat, ist dieser Ort für freie Software mindestens fragwürdig.¹⁰ Die Free Software Foundation (FSF) hält die Copilot Nutzung sogar für illegal.¹¹ In der Vergangenheit wurden “unliebsame” Repositories ohne Ankündigung geblockt oder Konten intransparent einfach gesperrt.¹²

Plattformwahl ist kein rein technisches Detail, sondern hat Auswirkungen auf Verfügbarkeit, Kontrolle, Moderation, Abhängigkeiten und ist ein legitimer Teil jeder Art von Dokumentation. Wenn Dir diese Punkte wichtig sind, dann dokumentiere das bewusst. Prüfe Alternativen, nutze Mirrors oder behalte zumindest eine Strategie im Hinterkopf, wie Du Dein Projekt unabhängig von einzelnen Anbietern hältst.

Lasse einfach das nachfolgende Bild auf Dich wirken, das die Erreichbarkeit und Downzeiten von GitHub für die Jahre vor und nach der Übernahme durch Microsoft visualisiert.¹³

Fazit

Dokumentation ist kein Anhängsel, sondern fester Bestandteil und “Handschrift” eines Projekts. In Diskussionen zu Netzwerk- oder Softwarethemen höre ich oft “Das mache ich mal eben in 5 Minuten” und zielt damit auf meine Zeitplanung, wo ich mit Blick auf die Dokumentation eher mit ein bis zwei Stunden für den gleichen Vorgang rechne.

Gerade bei kritischen oder komplexen Themen geht es nicht nur darum, etwas einfach umzusetzen, sondern auch es nachvollziehbar zu machen. Für andere und für einen selbst. Ich weiß doch selbst kaum noch, was ich vor zwei Wochen programmiert habe.

Das Schreiben von Dokumentationen ist ein Zeichen von reifer Softwareentwicklung und eines erwachsenen Projektmanagements.¹⁴

In diesem Sinne,
Euer Tomas Jakobs