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 die Readme.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.md bestimmen und daraus ableiten, welche Inhalte sie braucht.

  • … typische Bestandteile einer Readme.md nennen und in eine sinnvolle Reihenfolge bringen.

  • … Qualitätsmerkmale von Softwaredokumentation nennen und auf eine Readme.md anwenden.

  • … Überschriften, Hervorhebungen, Listen, Links, Bilder, Tabellen und Codeblöcke in Markdown notieren.

  • … erklären, warum die Readme.md bei 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.md und CHANGELOG.md sinnvoll 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.md wird 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.md auch diesen Fokus setzen. In jedem Fall wäre die Readme.md hier 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.

Mindmap der möglichen Bestandteile einer Readme.md (mit KI erstellt)

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)

    Artikel über Readme.md-Dateien

  • Bilder sollten immer auch einen ALT-Text enthalten:

    ![ein Bild mit normaler Bildunterschrift](https://oer-informatik.gitlab.io/db-sql/dml-select-queries/image/select-railroad-projektion-selektion.png)
    ein Bild mit normaler Bildunterschrift
  • 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 Linientabelle
    Eine Linientabelle
    Hier kommen die Überschriften
    hin
    Rechts Links Mittig Default
    Code geht auch Oder Formeln E = m \cdot c^2 Bei mehrzeiligem
    Text muss man
    mit HTML
    schummeln
    es 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 Bindestrich
    • Erster Gedanke

    • Nächster Gedanke

    • Letzter Gedanke

    1. Nummerierter Gedanke

    2. Nächste Nummer

    3. 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]: Quelle in 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 largest
    package 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

  1. Warum solltest Du vor dem Schreiben einer Readme.md die 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“

  1. 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“

  1. 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“

  1. 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“

  1. Warum sieht eine Readme.md auf 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“


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]


  1. siehe iX 06/2023 S.36 “Dokumentation und Nachhaltigkeit” (hinter Bezahlschranke)↩︎

  2. Quelle der steilen These↩︎

  3. Quelle der steilen These mit link↩︎

Titelbild: Foto von Pixabay von Pexels (CC0): https://www.pexels.com/de-de/foto/nahaufnahme-des-offenen-buches-256467/

Kommentare gerne per Mastodon, Verbesserungsvorschläge per gitlab issue (siehe oben). Beitrag teilen: