git Readme.md-Dateien erstellen
https://bildung.social/@oerinformatik/110440566399038321
https://oer-informatik.de/git04-readme-erstellen
Readme, Markdown, Softwaredokumentation, git, Repository, Zielgruppe, Qualitätsmerkmale, GitHub, GitLab
tl/dr; (ca. 16 min Lesezeit): Gute Software braucht gute Dokumentation - ohne unnötigen Aufwand. Eine erste Anlaufstelle ist häufig die
Readme.md-Datei in git-Repositorys. Aber: für wen schreibe ich die eigentlich? Was sollte, was muss da rein? Wie formatiere ich dieReadme.md-Datei mit Markdown [AI-Assisted]? (Zuletzt geändert am 09.11.2026)
Dieser Artikel ist Teil einer Artikelreihe über die Versionsverwaltung git: Erste Schritte und lokale Commits / git im Team und Remote nutzen / Versionieren mit Branches / Readme.md-Dateien erstellen / Workflows im Team / Übungsaufgaben
Schon fit in diesem Thema? Nutze die Kann-Liste und die Leitfragen unter dem Artikel als Checkliste, ob Du die relevanten Kompetenzen bereits hast.
Als Grundlagen zur Readme.md kann ich nach Durchlesen des Artikels…
… die Zielgruppen einer
Readme.mdbestimmen und daraus ableiten, welche Inhalte sie braucht.… typische Bestandteile einer
Readme.mdnennen und in eine sinnvolle Reihenfolge bringen.… Qualitätsmerkmale von Softwaredokumentation nennen und auf eine
Readme.mdanwenden.… Überschriften, Hervorhebungen, Listen, Links, Bilder, Tabellen und Codeblöcke in Markdown notieren.
… erklären, warum die
Readme.mdbei jeder Änderung der Software mit gepflegt werden muss.
Darüber hinaus kann ich als Expertenwissen…
… Unterschiede zwischen Markdown-Varianten (GitHub, GitLab, pandoc) bei Tabellen, Fußnoten, Formeln und Diagrammen berücksichtigen.
… ergänzende Dateien wie
LICENSE,CONTRIBUTING.mdundCHANGELOG.mdsinnvoll einsetzen.
First things first: Für wen schreibe ich die Readme.md und was will ich ihr/ihm sagen?
Was für diesen Text gilt, gilt auch für jede Readme.md: Wir müssen uns zunächst im Klaren sein, wer unsere Adressaten sind und welche Nachricht wir ihnen übermitteln wollen. Ein paar Beispiele:
Das Projekt vereinfacht einen Workflow, den ich alle paar Monate habe. Es ist sehr unwahrscheinlich, dass jemand anders ein ähnliches Problem hat und das Projekt nutzen wird. Die Nachricht für mein zukünftiges ich wäre also etwa “Wie wende ich die Software an?”, “Wo habe ich nochmal die Konfigurations-Flags versteckt?”. Für alle anderen fasse ich kurz zusammen, welches Problem das Projekt löst, damit sie wissen, ob dieses Projekt für sie relevant ist.
Ich habe eine sehr spezielle Library erstellt, die nur in unserem Unternehmen genutzt wird (und auch gar nicht öffentlich verteilt wird). Der Adressatenkreis grenzt sich damit auf mein zukünftiges ich und Kolleg*innen ein, denn auch die
Readme.mdwird das Intranet nie verlassen. Als User und Developer wollen die Adressaten zusätzlich zu dem oben genannten wissen, wie sich das Projekt in die Unternehmensumgebung integriert, wo die Schwachstellen und aktuellen ToDos sind.Ich habe ein Plugin für einen weit verbreiteten Editor erstellt, den viele nutzen. Mein Adressat wären also Anwender, die wissen wollen, was dieses Plugin kann, wie ich es installiere und benutze. Vielleicht ist meine Intention auch, Mitentwickler*innen zu finden - dann sollte die
Readme.mdauch diesen Fokus setzen. In jedem Fall wäre dieReadme.mdhier ein Aushängeschild und sollte auch die nötige Aufmerksamkeit bei der Erstellung genießen.Ich habe ein Projekt für die Berufsschule / die Uni erstellt. Das eigentliche Projektziel ist, zu zeigen, dass ich bestimmte Fertigkeiten anwenden kann. Adressaten wären v.a. die Bewertenden, meine Peergroup oder andere, die ähnliche Projekte umsetzen. Im Fokus sollte also auch die neu erlernte Fertigkeit stehen.
Ich denke, es ist klar geworden: ein OpenSource-Projekt benötigt eine andere Readme.md als ein firmeninternes Projekt usw. Bei allem folgenden sollte also stets der Adressatenkreis im Blick bleiben: brauche ich diesen Punkt in meinem Fall wirklich?
Qualitätsmerkmale von Softwaredokumentation
Häufig ist die Readme.md-Datei neben Testfällen, aussagekräftigen Methoden- und Variablennamen und Inline-Kommentaren die einzige Dokumentation, die zu einer Software besteht. Sie muss daher von Anfang an in der Qualitätssicherung mitgedacht werden - und bei jeder Veränderung der Software mit qualitätsgesichert werden.
Die beiden IT-Sicherheitsexpert*innen Caroline Krohn und Manuel Atug stellen in diesem Zusammenhang einen Bezug zwischen IT-Dokumentationen und Nachhaltigkeit her, der die Verantwortung für IT-Sicherheit, sicheren Betrieb auch für “zukünftige Generationen” (also auch kurzfristige Nachfolger) und Transparenz mit der Dokumentation herausstellt.1.
Die von ihnen genannten Qualitätskriterien, die insbesondere für die Dokumentation von freier Software gelten, sind:
Vollständigkeit,
Übersichtlichkeit,
Nachvollziehbarkeit,
Verständlichkeit,
Strukturiertheit,
Korrektheit,
Objektivität und
Editierbarkeit.
Auch diese Qualitätsmerkmale müssen natürlich auf das jeweilige Projekt zugeschnitten werden. Als Ausgangspunkt, von dem aus man begründet abweichen kann, halte ich diese Auflistung aber für sehr geeignet.
Inhalt einer Readme: Was sind denkbare Bestandteile?
Die folgende Mindmap fasst die Fragen zusammen, die eine Readme.md beantworten kann. Welche Äste Dein Projekt braucht, hängt von der Zielgruppe ab.
Ich sehe gerne auf den ersten Blick im Repository, ob das jeweilige Projekt für mich überhaupt relevant ist. Daher wünsche ich mir häufig, dass ich auf den ersten Blick die Frage beantworten kann:
Was ist das für ein Projekt - und wann darf ich es benutzen / kopieren / weiterverarbeiten?
Projekttitel
Kurze Beschreibung des Projekts/Repos als oneliner (nach der Lizenz nochmal etwas ausführlicher)
Welche Lizenz nutzt das Projekt?
Damit wären in den ersten drei Zeilen die wesentlichen Informationen gegeben. Sollte das Projekt länger werden, wäre jetzt ein guter Platz für ein Inhaltsverzeichnis. Denn ab hier kann man mit selbst gewähltem Detaillierungsgrad sehr ausführlich werden.
Welches Problem löst das Projekt?
Welche Ausgangslage gab es und wo lag das Problem, dass durch das Projekt gelöst wird?
Für welche Einsatzgebiete ist dieses Projekt gedacht?
Gerade bei öffentlichem Sourcecode ist dieser Absatz wichtig.
Wie installiere ich das Projekt
Woher bekomme ich den Quellcode / die Binaries (Installationsdateien)?
Wie wird das Projekt installiert? Gibt es Screencasts oder Schritt-für-Schritt Anleitungen des Installationsprozesses?
Welche Voraussetzungen und Abhängigkeiten hat das Projekt, welche Ressourcen werden genutzt und benötigt?
Wie nutze ich das Projekt
Wie wird es gestartet?
Wie führe ich die Standard-Anwendungsfälle durch (ggf. Screenshots, Screencasts)?
Auf welchen Benutzertests beruht die Abnahme? Damit sind i.d.R. die häufigsten Anwendungsfälle dokumentiert.
Bei größeren Projekten muss man sicher auf externe Quellen verweisen: Wo finde ich die Anwender-Dokumentation?
Wer hat alles zum Projekt beigetragen?
Häufig basieren Projekte auf Vorgängerprojekten oder haben Anleitungen genutzt. Die Quellen zu nennen (und zu verlinken) hilft allen, die Informationen zu bestimmten Problemen suchen. Und es ist ein Dank an die Projekte, die uns selbst geholfen haben.
Falls an diesem Projekt selbst mehrere Entwickler*innen mitgearbeitet haben, kann es sinnvoll sein, hier eine Liste mit Kontaktdaten zu nennen - oder ggf. auf die Changelog-Datei zu verweisen, aus der hervorgeht, wer alles beigetragen hat.
Was kann ich tun, wenn ich Fragen zum Projekt habe?
Welche bekannten Bugs/Kompatibilitätsprobleme gibt es?
Wo kann ich Fragen an die Entwicklerin stellen (Kontakt Autoren)?
Wo kann ich Bugreports einsehen und durchsuchen?
Wo kann ich Featurerequests erstellen?
Welche Features sind noch geplant?
Wie kann ich das Projekt parametrisieren, verändern, weiterentwickeln?
Welchen Aufbau, welche Struktur hat das Projekt? Hier helfen Diagramme und Visualisierungen!
Welche öffentlichen Methoden sollte man kennen?
Wo finde ich eine Entwicklerdokumentation?
Wo finde ich den Quelltext?
Wie starte ich die Testsuite?
Welche Entscheidungen wurden im Projektverlauf getroffen, die für andere in ähnlicher Situation interessant sein können?
Warum wurden andere alternative Lösungswege/Techniken nicht genutzt?
Welche Probleme/offene Fragen gibt es momentan bei der Umsetzung/Entwicklung?
Eine Vorlage für den Start
Aus den Fragen oben ergibt sich ein Gerüst, das Du je nach Zielgruppe kürzt oder erweiterst. Die Abschnitte stehen in der Reihenfolge, in der Lesende sie typischerweise brauchen:
# Mitfahrbörse-API
REST-Schnittstelle für eine Mitfahrbörse an Schulen. Lizenz: [MIT](LICENSE)
## Worum geht es?
Kurz das Problem, das das Projekt löst, und für wen es gedacht ist.
## Installation
Voraussetzungen (z. B. Python 3.12, MariaDB 11) und die Schritte bis zum Start:
```bash
git clone https://gitlab.com/beispiel/mitfahrboerse-api.git
cd mitfahrboerse-api
pip install -r requirements.txt
```
## Nutzung
Start, die zwei, drei wichtigsten Anwendungsfälle, ggf. Screenshots.
## Entwicklung und Tests
Aufbau des Projekts, Start der Tests, Hinweise für Mitwirkende (siehe CONTRIBUTING.md).
## Bekannte Probleme und Kontakt
Wo Fehler gemeldet werden, wer ansprechbar ist.
## Danke
Vorlagen, Bibliotheken und Personen, auf denen das Projekt aufbaut.Was nicht in die Readme.md passt, lagert man in eigene Dateien aus, die die gängigen git-Dienste ebenfalls erkennen: den Lizenztext in LICENSE, Regeln für Mitwirkende in CONTRIBUTING.md und die Liste der Änderungen je Version in CHANGELOG.md.
Kleines Markdown HowTo für die Readme.md
Die Readme.md-Dateien in git-Repositories werden mithilfe von Markdown formatiert. Markdown verfügt über eine zurückhaltende Auszeichnung (Formatierungsbefehle). Dadurch bleiben die Quelltexte leicht lesbar und in jedem Editor bearbeitbar.
Ein guter Start zum Ausprobieren von Markdown ist beispielsweise die Vorschau in Visual Studio Code (Strg+Umschalt+V) oder ein Online-Editor wie HedgeDoc. Markdown gibt es in mehreren Varianten: GitHub und GitLab nutzen jeweils eine eigene Erweiterung des Standards CommonMark („GitHub Flavored Markdown“ bzw. „GitLab Flavored Markdown“), dieser Artikel selbst wird mit pandoc übersetzt. Die meisten Elemente funktionieren überall; wo es Unterschiede gibt, steht ein Hinweis dabei. Die wichtigsten Auszeichnungselemente von Markdown sind folgende:
Absätze werden immer durch eine Leerzeile gekennzeichnet.
Dieser Text wird in eine Zeile geschrieben. Dieser nicht.Dieser Text wird in eine Zeile geschrieben.
Dieser nicht.
Überschriften werden mit vorangestelltem
#notiert (Leerzeilen davor und danach!):# Überschrift ## Unterüberschrift ### Unterunterüberschrift...Ich kann kursiv, fett oder fett und kursiv schreiben.
Ich kann _kursiv_, **fett** oder **_fett und kursiv_** schreiben.Links werden wie folgt notiert:
[Artikel über Readme.md-Dateien](https://oer-informatik.de/git04-readme-erstellen)Bilder sollten immer auch einen ALT-Text enthalten:

Tabellen lassen sich am einfachsten so darstellen (die Beschriftung mit
Table:versteht nur pandoc):| Hier | kommen | die |Überschriften<br/> hin| |--------:|:-------|:--------:|---------| | Rechts | Links | Mittig |Default | |Code geht `auch` |Oder Formeln $E = m \cdot c^2$ |Bei mehrzeiligem<br/>Text muss man<br/>mit HTML<br/>schummeln|| | es kann | auch etwas leer | |sein | Table: Eine LinientabelleEine Linientabelle Hier kommen die Überschriften
hinRechts Links Mittig Default Code geht auchOder Formeln E = m \cdot c^2 Bei mehrzeiligem
Text muss man
mit HTML
schummelnes kann auch etwas leer sein Aufzählungen können auf unterschiedliche weise realisiert werden:
- Erster Gedanke - Nächster Gedanke - Letzter Gedanke 1. Nummerierter Gedanke 2. Nächste Nummer 2. Trotz falscher Zahl korrekt in der Ausgabe * Ohne Nummerierung Variante 2 * Wie bei BindestrichErster Gedanke
Nächster Gedanke
Letzter Gedanke
Nummerierter Gedanke
Nächste Nummer
Trotz falscher Zahl korrekt in der Ausgabe
Ohne Nummerierung Variante 2
Wie bei Bindestrich
Fußnoten werden in pandoc so umgesetzt (GitHub und GitLab verstehen nur die Form
Text[^1]mit der Erläuterung[^1]: Quellein einer eigenen Zeile).Steile These^[Quelle der steilen These] Steile These aus dem Internet^[Quelle der steilen These [mit link](http://die.wirklich-ganze-wahrheit.de)]Steile These2
Steile These aus dem Internet3
Codeschnipsel haben das folgende Format (Leerzeile vor und hinter dem Codeblock setzen!):
```python def largest_signed_int(byte_count): largest = 2**(byte_count-1)-1 return largest ``` ```java package de.csbme.ifaxx public class Konto{ private Double kontostand; public Double getKontostand(){ return kontostand; } } ``` ```sql SELECT * FROM db.table WHERE text LIKE '%MSSQL%' ```def largest_signed_int(byte_count): largest = 2**(byte_count-1)-1 return largestpackage de.csbme.ifaxx public class Konto{ private Double kontostand; public Double getKontostand(){ return kontostand; } }SELECT * FROM db.table WHERE text LIKE '%MSSQL%'In einigen Webfrontends von git-Diensten (z. B. GitLab, sofern in der Instanz aktiviert) werden PlantUML-Scripte direkt als Grafik interpretiert. GitHub und GitLab zeichnen außerdem Diagramme in der Notation Mermaid (Codeblock mit Sprachangabe
mermaid):```plantuml @startuml class Rocket{ -width:int -height:int +move() +draw(screen: Screen) } @enduml ```Mathematische Formeln können mit der LaTeX-Notation in Dollarzeichen eingefasst werden. Die Notation ist etwas Übungssache, aber Seiten wie der Editor von zahlen-kern.de sind eine gute Einstiegshilfe.
$$\eta = \frac{W_{ab}}{W_{zu}}$$\eta = \frac{W_{ab}}{W_{zu}}
$$ c = \sqrt{a^2 + b^2} = \sqrt{{3{,}0\,\mathrm{cm}}^2 + {4{,}0\,\mathrm{cm}}^2} = \sqrt{25\,\mathrm{cm^2}} = 5{,}0\,\mathrm{cm}$$c = \sqrt{a^2 + b^2} = \sqrt{{3{,}0\,\mathrm{cm}}^2 + {4{,}0\,\mathrm{cm}}^2} = \sqrt{25\,\mathrm{cm^2}} = 5{,}0\,\mathrm{cm}
$$ I = \frac{U}{R} = \frac{5\,\mathrm{V}}{100\,\mathrm{k\Omega}} = 50\,\mathrm{\mu A}$$I = \frac{U}{R} = \frac{5\,\mathrm{V}}{100\,\mathrm{k\Omega}} = 50\,\mathrm{\mu A}
$$ Q_{A} = (\overline{Q_{B}} \land Q_{C}) \lor \overline{(Q_{C} \land \lnot Q_{D})}$$Q_{A} = (\overline{Q_{B}} \land Q_{C}) \lor \overline{(Q_{C} \land \lnot Q_{D})}
Wenn die so erstellte Markdown-Datei dann noch Readme.md heißt, und sich im Wurzelverzeichnis des Projektrepositorys befindet, dann wird sie auf der Website des Repositorys bei gitlab, github, bitbucket und Co. direkt geöffnet.
Fazit
Es gibt keinen einzig richtigen Weg ein Readme.md zu gestalten. Der erste und wichtigste Schritt ist es, sich Gedanken darüber zu machen, wem man mit dem Text wobei helfen will und darauf basierend Inhalt und Umfang anzupassen. Wenn dann die Datei noch mit in die Qualitätssicherung mit aufgenommen wird (auch bei Erweiterungen), ist man auf einem guten Weg.
Die oben genannten Aspekte können sicher dabei unterstützen, eine passend zugeschnittene Readme.md zu erstellen. Die eigentliche Arbeit ist aber, die passende Form, den passenden Inhalt und den passenden Umfang individuell zu definieren.
Teile dieses Tutorials
Leitfragen
- Warum solltest Du vor dem Schreiben einer
Readme.mddie Zielgruppe festlegen?
Eine Bibliothek für das eigene Team braucht andere Informationen als ein Open-Source-Plugin oder ein Schulprojekt. Erst wenn klar ist, wer die Datei liest und was diese Person wissen will, kannst Du Inhalt und Umfang passend wählen. siehe Abschnitt „First things first“
- Welche Informationen gehören in die ersten Zeilen einer
Readme.md?
Projekttitel, eine kurze Beschreibung in einem Satz und die Lizenz. Damit erkennt man sofort, ob das Projekt relevant ist und ob man es nutzen und weiterverarbeiten darf. siehe Abschnitt „Inhalt einer Readme“
- Nenne vier Qualitätsmerkmale von Softwaredokumentation.
Zum Beispiel Vollständigkeit, Übersichtlichkeit, Nachvollziehbarkeit, Verständlichkeit, Strukturiertheit, Korrektheit, Objektivität und Editierbarkeit. siehe Abschnitt „Qualitätsmerkmale von Softwaredokumentation“
- Wie notierst Du in Markdown eine Überschrift zweiter Ebene, einen Link und einen Python-Codeblock?
Mit ## Überschrift, mit [Linktext](https://…) und mit drei Backticks samt Sprachangabe python vor und drei Backticks nach dem Code, jeweils mit Leerzeilen davor und danach. siehe Abschnitt „Kleines Markdown HowTo“
- Warum sieht eine
Readme.mdauf GitHub manchmal anders aus als in einer Vorschau auf dem eigenen Rechner?
Es gibt mehrere Markdown-Varianten. GitHub und GitLab unterstützen z. B. Fußnoten nur in der Form [^1], keine Tabellenbeschriftung mit Table:, und PlantUML-Diagramme stellt nur GitLab dar. siehe Abschnitt „Kleines Markdown HowTo“
Links und weitere Informationen
für die Syntax: der Markdown-Leitfaden von GitHub und die Markdown-Dokumentation von GitLab
als Sammlung guter Beispiele: die Liste awesome-readme
zur Lizenzwahl: die Übersicht choosealicense.com
Hinweis zur Nachnutzung als Open Educational Resource (OER)
Dieser Artikel und seine Texte, Bilder, Grafiken, Code und sonstiger Inhalt sind - sofern nicht anders angegeben - lizenziert unter CC BY 4.0. Nennung gemäß TULLU-Regel bitte wie folgt: “git Readme.md-Dateien erstellen” von oer-informatik.de (H. Stein), Lizenz: CC BY 4.0. Der Artikel wurde unter https://oer-informatik.de/git04-readme-erstellen veröffentlicht, die Quelltexte sind in weiterverarbeitbarer Form verfügbar im Repository unter https://gitlab.com/oer-informatik/devoptools/git. Erstellt mit KI-Assistenz; von mir umfassend redaktionell überarbeitet, geprüft und freigegeben. Stand: 09.11.2026.
[Kommentare zum Artikel lesen, schreiben] / [Artikel teilen] / [gitlab-Issue zum Artikel schreiben]
siehe iX 06/2023 S.36 “Dokumentation und Nachhaltigkeit” (hinter Bezahlschranke)↩︎
Quelle der steilen These↩︎
Titelbild: Foto von Pixabay von Pexels (CC0): https://www.pexels.com/de-de/foto/nahaufnahme-des-offenen-buches-256467/
