Readme: Alles Wichtige im Überblick – inklusive Vorlage

Readme – in diesem Namen steckt bereits die Aufforderung „Lies mich“. Und genau so ist der Begriff auch gemeint. Die Readme-Datei ist die erste Datei, die ein Entwickler anschauen sollte, bevor er ein Projekt beginnt. Ebenso ist es wichtig, dass Entwickler wissen, wie sie eine gute Readme-Datei schreiben, um alle relevanten Informationen kompakt wiederzugeben.

Was ist eine Readme-Datei und wozu brauche ich sie?

Eine Readme-Datei – häufig als Readme.txt oder Readme.md erstellt – enthält üblicherweise wichtige Informationen zu dem jeweiligen System, Projekt oder der jeweiligen Software. Damit Nutzer die Datei direkt sehen, liegt sie im Idealfall in der obersten Verzeichnisebene.

Tipp

Häufig wird README im Dateinamen komplett in Großbuchstaben geschrieben. Systeme, die zwischen Groß- und Kleinschreibung unterscheiden, listen die Datei dann vor allen anderen Dateien, die mit Kleinbuchstaben beginnen.

Für die unterschiedlichen Anwender erfüllt die Datei auch unterschiedliche Zwecke:

  • Für den Endnutzer klärt eine Readme-Datei mögliche Fragen zur Installation, zum Update oder zur Verwendung einer Software.
  • Für die eigene Entwicklungsarbeit bietet eine Readme-Datei zwei Vorteile. Zum einen liefert eine vor dem Entwicklungsstart geschriebene Readme-Datei eine Leitlinie für die Umsetzung des Projektes. Zum anderen hilft sie bei einem schnellen Wiedereinstieg, sollte ein Projekt über längere Zeit pausiert worden sein.
  • Für andere Entwickler verdeutlicht eine Readme-Datei den Kodex und liefert wichtige Hinweise zur Weiterentwicklung beziehungsweise Anwendung eines Systems, einer Software oder von Open-Source-Projekten.

Was sollte in einer Readme-Datei stehen?

Je nach Zweck, den die Readme-Datei erfüllt, bieten sich unter anderem folgende Inhalte an:

  • Eine generelle Beschreibung des Systems oder Projektes.
  • Der Projektstatus ist vor allem dann wichtig, wenn sich das Projekt noch in der Entwicklung befindet. Erwähnen Sie in der Datei geplante Änderungen und die Entwicklungsrichtung oder geben Sie direkt an, wenn ein Projekt fertig entwickelt ist.
  • Die Anforderungen an die Entwicklungsumgebung für die Integration.
  • Eine Anleitung für die Installation und Bedienung.
  • Eine Auflistung der verwendeten Technologien und gegebenenfalls Links zu weiteren Informationen zu den Technologien.
  • Open-Source-Projekte, die Entwickler eigenständig verändern oder erweitern, sollten in der Readme.md einen Abschnitt zur „gewünschten Zusammenarbeit“ enthalten. Wie geht man mit Problemen um? Wie sollen Entwickler die Änderungen vorantreiben?
  • Bekannte Bugs und eventuelle Fehlerbehebungen.
  • FAQ-Bereich mit allen bisher gestellten Fragen.
  • Copyrights und Lizenzinformationen.

Es ist wichtig, die Readme-Datei immer so zu schreiben, dass sie auf den Endnutzer abgestimmt ist. Nur so können Sie die meisten potenziellen Fragen klären.

Mögliche Dateiformate einer Readme-Datei

Eine Readme-Datei können Sie in jedem beliebigen Textdatei-Format schreiben und abspeichern. Die Formate reichen von Readme.txt, über Readme.doc bis zu readme.1st. Je nachdem, auf welcher Plattform die Software laufen soll, ist das Format der Readme-Datei an das jeweilige System und dessen Textprogramm angepasst. So ist sichergestellt, dass das Textprogramm die Datei lesen kann.

Heute nutzen Entwickler am häufigsten das Format Readme.md. Doch was ist eine .md-File? Die Dateiendung weist auf eine Readme-Datei im Markdown-Format hin. Markdown wandelt Text mithilfe von einfachen Formatierungszeichen in HTML um. Eine gut formatierte und strukturierte Readme-Datei gibt den Nutzern einen umfassenden Überblick über das Projekt.

Readme.md: Ein Beispiel im Markdown-Format

Wir zeigen Ihnen, wie ein Readme.md Stück für Stück aufgebaut ist und welche Formatierungsmöglichkeiten es mit dem Markdown-Format gibt. Um eine globale Zusammenarbeit zu ermöglichen und Sprachbarrieren zu vermeiden, sollten Sie die Readme-Datei immer auf Englisch schreiben.

Readme-Beispiel im Markdown-Format:

# Project name
***
Short Description about the project.
Tipp

Mit „***“ fügen Sie eine horizontale Trennlinie ein.

An erster Stelle der Readme-Datei stehen ein aussagekräftiger Projektname und eine kurze Erklärung, um was für ein Projekt es sich handelt. Im Markdown leitet eine Raute „#“ immer eine Überschrift ein. Die Anzahl der Rauten bestimmt dabei die Überschriftenarten:

# Headline H1
## Headline H2
### Headline H3
#### Headline H4 
##### Headline H5
###### Headline H6

Bei einer umfangreichen Dokumentation sorgt ein übersichtliches Inhaltsverzeichnis für einen guten Überblick:

## Table of Contents
1. [General Info](#general-info)
2. [Technologies](#technologies)
3. [Installation](#installation)
4. [Collaboration](#collaboration)
5. [FAQs](#faqs)

Das Inhaltsverzeichnis der Readme.md lässt sich mit einer geordneten Liste gut strukturieren. Einfach die entsprechende Zahl am Anfang der Zeile einfügen und die Liste wird erstellt.

GitHub fügt automatisch IDs zu den Überschriften in der Readme-Datei hinzu. Die IDs ergeben sich aus dem Namen der Überschrift und Bindestriche „-" ersetzen die Leerzeichen. Sie lassen sich wunderbar für die Ankernavigation des Inhaltsverzeichnisses nutzen. Ist die Readme.md für eine andere Plattform gedacht, die die Überschriften nicht automatisch mit IDs versehen, lässt sich die Ankernavigation mit HTML erzeugen:

## Table of Contents
<a name="general-info"></a>
### General Info

Nach dem Inhaltsverzeichnis folgen die jeweiligen Inhaltsblöcke zu den einzelnen Punkten:

## General Info
***
Write down the general informations of your project. It is worth to always put a project status in the Readme file. This is where you can add it. 
### Screenshot
![Image text](/path/to/the/screenshot.png)

Generelle Infos zum Projekt sind wichtig, um sich über die kurze Erklärung hinaus einen Eindruck von diesem zu verschaffen. Mit Markdown können Sie auch Grafiken, Screenshots oder andere Bilder in die Dokumentation einfügen. Dafür einfach ein beschreibendes Wort in eckige Klammern schreiben, gefolgt von der URL zum Bild in runden Klammern (ohne Leerzeichen dazwischen). Davor setzen Sie ein Ausrufezeichen, damit das Markdown es als Bilddatei interpretiert.

## Technologies
***
A list of technologies used within the project:
* [Technologie name](https://example.com): Version 12.3 
* [Technologie name](https://example.com): Version 2.34
* [Library name](https://example.com): Version 1234

Im Markdown-Format erstellen Sie Aufzählungspunkte einer ungeordneten Liste mit einem Sternchen „*“ am Anfang der Zeile.

Links lassen sich an beliebiger Stelle in die Readme.md einfügen. Der Aufbau ähnelt sehr stark einer Bilddatei, nur ohne das Ausrufezeichen am Anfang der Zeile. Schreiben Sie das zu verlinkende Wort in eckige Klammern, gefolgt vom Pfad zur Website in runden Klammern (ebenfalls ohne Leerzeichen dazwischen).

Hinweis

Die Datei sollte immer im gleichen Repository liegen. Sie können auch andere öffentlich verfügbare Dateien verwenden. Jedoch besteht die Gefahr, dass der Eigentümer diese Dateien irgendwann löscht und sie dadurch aus Ihrer Readme.md verschwinden.

## Installation
***
A little intro about the installation. 
```
$ git clone https://example.com
$ cd ../path/to/the/file
$ npm install
$ npm start
```
Side information: To use the application in a special environment use ```lorem ipsum``` to start

Da eine Readme-Datei oftmals im Kontext der Software-Entwicklung eingesetzt wird, ist es sinnvoll Beispiele von Quelltext in das Dokument aufzunehmen. Markdown hat auch hierfür eine Formatierungsoption. Der Code lässt sich mit „```” am Anfang und Ende formatieren. Sie können Codeteile auch direkt im Text verwenden. 

## Collaboration
***
Give instructions on how to collaborate with your project.
> Maybe you want to write a quote in this part. 
> It should go over several rows?
> This is how you do it.

Ein „>“ am Anfang der Zeile wandelt den Text in ein Zitat um. 

## FAQs
***
A list of frequently asked questions
1. **This is a question in bold**
Answer of the first question with _italic words_. 
2. __Second question in bold__ 
To answer this question we use an unordered list:
* First point
* Second Point
* Third point
3. **Third question in bold**
Answer of the third question with *italic words*.
4. **Fourth question in bold**
| Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead |
|:--------------|:-------------:|--------------:|
| text-align left | text-align center | text-align right |

Geordnete und ungeordnete Listen lassen sich in der Readme.md auch in Kombination verwenden. Dazu einfach die nummerierte Liste mit der entsprechenden Zahl fortführen.

Beispielhaft haben wir kursive und fette Worte beziehungsweise Textabschnitte integriert. Einen kursiven Schriftsatz erzeugen Sie, indem Sie dem jeweiligen Wort oder Textabschnitt ein einfaches Sternchen „*“ oder einen Unterstrich „_“ voran oder nachstellen. Für Fettmarkierungen setzen Sie doppelte Sternchen oder Unterstriche ein.

Auch Tabellen lassen sich mithilfe des Markdown-Formats in die Readme.md einfügen. Sie können sie mit Pipes „|“ und Bindestrichen „-"erzeugen. Die Doppelpunkte geben an, ob der Text links, rechts oder zentriert ausgerichtet sein soll.

Readme Beispiel-Vorlage

Anbei finden Sie noch einmal alle Beispiele aus dem Artikel zusammengefasst als eine Readme-Vorlage:

## Table of Contents
1. [General Info](#general-info)
2. [Technologies](#technologies)
3. [Installation](#installation)
4. [Collaboration](#collaboration)
5. [FAQs](#faqs)
### General Info
***
Write down the general informations of your project. It is worth to always put a project status in the Readme file. This is where you can add it. 
### Screenshot
![Image text](https://www.united-internet.de/fileadmin/user_upload/Brands/Downloads/Logo_IONOS_by.jpg)
## Technologies
***
A list of technologies used within the project:
* [Technologie name](https://example.com): Version 12.3 
* [Technologie name](https://example.com): Version 2.34
* [Library name](https://example.com): Version 1234
## Installation
***
A little intro about the installation. 
```
$ git clone https://example.com
$ cd ../path/to/the/file
$ npm install
$ npm start
```
Side information: To use the application in a special environment use ```lorem ipsum``` to start
## Collaboration
***
Give instructions on how to collaborate with your project.
> Maybe you want to write a quote in this part. 
> It should go over several rows?
> This is how you do it.
## FAQs
***
A list of frequently asked questions
1. **This is a question in bold**
Answer of the first question with _italic words_. 
2. __Second question in bold__ 
To answer this question we use an unordered list:
* First point
* Second Point
* Third point
3. **Third question in bold**
Answer of the third question with *italic words*.
4. **Fourth question in bold**
| Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead |
|:--------------|:-------------:|--------------:|
| text-align left | text-align center | text-align right |
Tipp

Mit dem WYSIWYG-Editor von Dillinger erstellen Sie schnell und einfach online eine Readme.md.

War dieser Artikel hilfreich?