Readme – in diesem Namen steckt bereits die Auf­for­de­rung „Lies mich“. Und genau so ist der Begriff auch gemeint. Die Readme-Datei ist die erste Datei, die ein Ent­wick­ler anschauen sollte, bevor er ein Projekt beginnt. Ebenso ist es wichtig, dass Ent­wick­ler wissen, wie sie eine gute Readme-Datei schreiben, um alle re­le­van­ten In­for­ma­tio­nen kompakt wie­der­zu­ge­ben.

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

Eine Readme-Datei – häufig als Readme.txt oder Readme.md erstellt – enthält üb­li­cher­wei­se wichtige In­for­ma­tio­nen zu dem je­wei­li­gen System, Projekt oder der je­wei­li­gen Software. Damit Nutzer die Datei direkt sehen, liegt sie im Idealfall in der obersten Ver­zeich­nis­ebe­ne.

Tipp

Häufig wird README im Da­tei­na­men komplett in Groß­buch­sta­ben ge­schrie­ben. Systeme, die zwischen Groß- und Klein­schrei­bung un­ter­schei­den, listen die Datei dann vor allen anderen Dateien, die mit Klein­buch­sta­ben beginnen.

Für die un­ter­schied­li­chen Anwender erfüllt die Datei auch un­ter­schied­li­che Zwecke:

  • Für den Endnutzer klärt eine Readme-Datei mögliche Fragen zur In­stal­la­ti­on, zum Update oder zur Ver­wen­dung einer Software.
  • Für die eigene Ent­wick­lungs­ar­beit bietet eine Readme-Datei zwei Vorteile. Zum einen liefert eine vor dem Ent­wick­lungs­start ge­schrie­be­ne Readme-Datei eine Leitlinie für die Umsetzung des Projektes. Zum anderen hilft sie bei einem schnellen Wie­der­ein­stieg, sollte ein Projekt über längere Zeit pausiert worden sein.
  • Für andere Ent­wick­ler ver­deut­licht eine Readme-Datei den Kodex und liefert wichtige Hinweise zur Wei­ter­ent­wick­lung be­zie­hungs­wei­se 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 Be­schrei­bung des Systems oder Projektes.
  • Der Pro­jekt­sta­tus ist vor allem dann wichtig, wenn sich das Projekt noch in der Ent­wick­lung befindet. Erwähnen Sie in der Datei geplante Än­de­run­gen und die Ent­wick­lungs­rich­tung oder geben Sie direkt an, wenn ein Projekt fertig ent­wi­ckelt ist.
  • Die An­for­de­run­gen an die Ent­wick­lungs­um­ge­bung für die In­te­gra­ti­on.
  • Eine Anleitung für die In­stal­la­ti­on und Bedienung.
  • Eine Auf­lis­tung der ver­wen­de­ten Tech­no­lo­gien und ge­ge­be­nen­falls Links zu weiteren In­for­ma­tio­nen zu den Tech­no­lo­gien.
  • Open-Source-Projekte, die Ent­wick­ler ei­gen­stän­dig verändern oder erweitern, sollten in der Readme.md einen Abschnitt zur „ge­wünsch­ten Zu­sam­men­ar­beit“ enthalten. Wie geht man mit Problemen um? Wie sollen Ent­wick­ler die Än­de­run­gen vor­an­trei­ben?
  • Bekannte Bugs und even­tu­el­le Feh­ler­be­he­bun­gen.
  • FAQ-Bereich mit allen bisher ge­stell­ten Fragen.
  • Co­py­rights und Li­zenz­in­for­ma­tio­nen.

Es ist wichtig, die Readme-Datei immer so zu schreiben, dass sie auf den Endnutzer ab­ge­stimmt ist. Nur so können Sie die meisten po­ten­zi­el­len Fragen klären.

Mögliche Da­tei­for­ma­te einer Readme-Datei

Eine Readme-Datei können Sie in jedem be­lie­bi­gen Textdatei-Format schreiben und ab­spei­chern. 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 Text­pro­gramm angepasst. So ist si­cher­ge­stellt, dass das Text­pro­gramm die Datei lesen kann.

Heute nutzen Ent­wick­ler am häu­figs­ten das Format Readme.md. Doch was ist eine .md-File? Die Da­tei­endung weist auf eine Readme-Datei im Markdown-Format hin. Markdown wandelt Text mithilfe von einfachen For­ma­tie­rungs­zei­chen in HTML um. Eine gut for­ma­tier­te und struk­tu­rier­te Readme-Datei gibt den Nutzern einen um­fas­sen­den Ü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 For­ma­tie­rungs­mög­lich­kei­ten es mit dem Markdown-Format gibt. Um eine globale Zu­sam­men­ar­beit zu er­mög­li­chen und Sprach­bar­rie­ren 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 ho­ri­zon­ta­le Trenn­li­nie ein.

An erster Stelle der Readme-Datei stehen ein aus­sa­ge­kräf­ti­ger Pro­jekt­na­me und eine kurze Erklärung, um was für ein Projekt es sich handelt. Im Markdown leitet eine Raute „#“ immer eine Über­schrift ein. Die Anzahl der Rauten bestimmt dabei die Über­schrif­ten­ar­ten:

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

Bei einer um­fang­rei­chen Do­ku­men­ta­ti­on sorgt ein über­sicht­li­ches In­halts­ver­zeich­nis 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 In­halts­ver­zeich­nis der Readme.md lässt sich mit einer ge­ord­ne­ten Liste gut struk­tu­rie­ren. Einfach die ent­spre­chen­de Zahl am Anfang der Zeile einfügen und die Liste wird erstellt.

GitHub fügt au­to­ma­tisch IDs zu den Über­schrif­ten in der Readme-Datei hinzu. Die IDs ergeben sich aus dem Namen der Über­schrift und Bin­de­stri­che „-" ersetzen die Leer­zei­chen. Sie lassen sich wunderbar für die An­ker­na­vi­ga­ti­on des In­halts­ver­zeich­nis­ses nutzen. Ist die Readme.md für eine andere Plattform gedacht, die die Über­schrif­ten nicht au­to­ma­tisch mit IDs versehen, lässt sich die An­ker­na­vi­ga­ti­on mit HTML erzeugen:

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

Nach dem In­halts­ver­zeich­nis folgen die je­wei­li­gen In­halts­blö­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 ver­schaf­fen. Mit Markdown können Sie auch Grafiken, Screen­shots oder andere Bilder in die Do­ku­men­ta­ti­on einfügen. Dafür einfach ein be­schrei­ben­des Wort in eckige Klammern schreiben, gefolgt von der URL zum Bild in runden Klammern (ohne Leer­zei­chen da­zwi­schen). Davor setzen Sie ein Aus­ru­fe­zei­chen, damit das Markdown es als Bilddatei in­ter­pre­tiert.

## 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 Auf­zäh­lungs­punk­te einer un­ge­ord­ne­ten Liste mit einem Sternchen „*“ am Anfang der Zeile.

Links lassen sich an be­lie­bi­ger Stelle in die Readme.md einfügen. Der Aufbau ähnelt sehr stark einer Bilddatei, nur ohne das Aus­ru­fe­zei­chen am Anfang der Zeile. Schreiben Sie das zu ver­lin­ken­de Wort in eckige Klammern, gefolgt vom Pfad zur Website in runden Klammern (ebenfalls ohne Leer­zei­chen da­zwi­schen).

Hinweis

Die Datei sollte immer im gleichen Re­po­si­to­ry liegen. Sie können auch andere öf­fent­lich ver­füg­ba­re Dateien verwenden. Jedoch besteht die Gefahr, dass der Ei­gen­tü­mer diese Dateien ir­gend­wann löscht und sie dadurch aus Ihrer Readme.md ver­schwin­den.

## 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-Ent­wick­lung ein­ge­setzt wird, ist es sinnvoll Beispiele von Quelltext in das Dokument auf­zu­neh­men. Markdown hat auch hierfür eine For­ma­tie­rungs­op­ti­on. Der Code lässt sich mit „```” am Anfang und Ende for­ma­tie­ren. 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 un­ge­ord­ne­te Listen lassen sich in der Readme.md auch in Kom­bi­na­ti­on verwenden. Dazu einfach die num­me­rier­te Liste mit der ent­spre­chen­den Zahl fort­füh­ren.

Bei­spiel­haft haben wir kursive und fette Worte be­zie­hungs­wei­se Text­ab­schnit­te in­te­griert. Einen kursiven Schrift­satz erzeugen Sie, indem Sie dem je­wei­li­gen Wort oder Text­ab­schnitt ein einfaches Sternchen „*“ oder einen Un­ter­strich „_“ voran oder nach­stel­len. Für Fett­mar­kie­run­gen setzen Sie doppelte Sternchen oder Un­ter­stri­che ein.

Auch Tabellen lassen sich mithilfe des Markdown-Formats in die Readme.md einfügen. Sie können sie mit Pipes „|“ und Bin­de­stri­chen „-"erzeugen. Die Dop­pel­punk­te geben an, ob der Text links, rechts oder zentriert aus­ge­rich­tet sein soll.

Readme Beispiel-Vorlage

Anbei finden Sie noch einmal alle Beispiele aus dem Artikel zu­sam­men­ge­fasst 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.

Zum Hauptmenü