Readme-Datei: Zusammenfassung mit Vorlage
Readme : Der Name selbst, Readme , gibt seinen Zweck an: gelesen zu werden. Die Readme- Datei ist die erste Datei , die ein Entwickler vor Beginn eines Projekts anzeigen sollte. Daher ist es auch wichtig zu wissen, wie eine gute Readme- Datei geschrieben wird , damit alle relevanten Informationen in kompakter Form dargestellt werden.
- Was ist eine Readme-Datei und wofür ist sie gedacht?
- Was sollte eine Readme-Datei enthalten?
- Mögliche Readme-Dateiformate
- Readme.md: Beispiel im Markdown-Format
- Beispiele: Readme-Dateivorlage
Was ist eine Readme-Datei und wofür ist sie gedacht?
Readme- Dateien , die häufig als readme.txt oder readme.md erstellt werden , enthalten häufig wichtige Informationen zu dem System, Projekt oder der Software, auf die sie verweisen. Damit Benutzer die Datei auf einen Blick leicht finden können, wird empfohlen, sie auf der obersten Ebene des Verzeichnisses zu suchen.
Im Allgemeinen wird der Dateiname in README in Großbuchstaben geschrieben . Auf diese Weise listen Systeme mit Groß- und Kleinschreibung die Datei vor allen anderen Dateien auf, die mit Kleinbuchstaben beginnen.
Die Datei hat auch unterschiedliche Zwecke für verschiedene Benutzertypen:
- Für den Endbenutzer klären Readme- Dateien mögliche Fragen zur Installation, Aktualisierung oder Verwendung von Software .
- Eine Readme- Datei bietet mehrere Vorteile für Ihre eigene Entwicklungsarbeit. Einerseits kann die Readme- Datei vor dem Start der Entwicklung selbst als Leitfaden für die Ausführung des Projekts dienen. Auf der anderen Seite hilft es auch, aufzuholen, wenn ein Projekt für längere Zeit unterbrochen wird.
- Für andere Entwickler erklären Readme- Dateien den Code und liefern wichtige Informationen zur Weiterentwicklung oder zur Verwendung von Open Source-Projekten, -Software oder -Systemen.
Was sollte eine Readme-Datei enthalten?
Eine Readme- Datei kann je nach Verwendungszweck folgende Inhalte bieten:
- Eine allgemeine Beschreibung des Systems oder Projekts.
- Der Status des Projekts, der besonders wichtig ist, wenn sich das Projekt noch in der Entwicklung befindet. Es erwähnt die geplanten Änderungen und die Entwicklungsrichtung des Projekts und wird direkt angegeben, wenn ein Projekt abgeschlossen ist.
- Die Anforderungen der Entwicklungsumgebung für die Integration.
- Eine Anleitung zur Installation und zum Betrieb.
- Eine Liste der verwendeten Technologien und gegebenenfalls Links zu weiteren Informationen.
- Open Source-Projekte, die geändert oder entwickelt werden können, sollten einen gewünschten Abschnitt für die Zusammenarbeit in der Datei readme.md enthalten. Wie können Sie Fehler beheben ? Wie sollen Entwickler Veränderungen vorantreiben?
- Bekannte Fehler und mögliche Fehlerbehebungen.
- Abschnitt mit häufig gestellten Fragen mit allen bisher aufgeworfenen Fragen.
- Informationen zu Urheberrechten und Lizenzen.
Es ist wichtig, die Readme-Datei immer in einer für den Endbenutzer geeigneten Sprache zu schreiben . Nur dann können die meisten Fragen geklärt werden.
Mögliche Readme-Dateiformate
Sie können eine Readme- Datei in einem beliebigen Textdateiformat schreiben und speichern . Die Formate reichen von readme.txt bis readme.doc und readme.1st. Abhängig von der Plattform, auf der die Software ausgeführt werden soll , wird das Dateiformat an das betreffende System und an Ihr Textanzeigeprogramm angepasst. Dies stellt sicher, dass das Textprogramm die Datei lesen kann.
Heutzutage verwenden Entwickler im Allgemeinen das readme.md- Format , aber was ist eine .md-Datei? Die Dateierweiterung gibt an, dass es sich um eine Readme- Datei im Markdown-Format handelt. Markdown konvertiert Text mithilfe von Formatierungszeichen in HTML. Eine ordnungsgemäß gestaltete und strukturierte Readme- Datei bietet Benutzern eine vollständige Projektzusammenfassung.
Readme.md: Beispiel im Markdown-Format
Hier zeigen wir Ihnen jedes der Strukturelemente einer readme.md- Datei sowie die Möglichkeiten, die das Markdown-Format bietet. Um die weltweite Zusammenarbeit zu ermöglichen und Sprachbarrieren zu vermeiden, sollte die Readme- Datei immer in Englisch sein .
Readme- Beispiel im Markdown-Format:
# Project name *** Short Description about the project.
Mit drei Sternchen (***) können Sie eine horizontale Trennlinie einfügen.
Am Anfang der Readme- Datei befindet sich ein aussagekräftiger Projektname und eine kurze Erläuterung des Projekttyps. In Markdown führt das Nummernzeichen ( # ) immer eine Überschrift ein. Die Anzahl der Pads bestimmt den Headertyp:
# Headline H1 ## Headline H2 ### Headline H3 #### Headline H4 ##### Headline H5 ###### Headline H6
Wenn die Dokumentation umfangreich ist, bietet ein klarer Index einen guten Überblick:
## Table of Contents 1. [General Info](#general-info) 2. [Technologies](#technologies) 3. [Installation](#installation) 4. [Collaboration](#collaboration) 5. [FAQs](#faqs)
Der Inhaltsindex von readme.md kann einfach mit einer geordneten Liste strukturiert werden. Geben Sie einfach die Nummer ein, die dem Zeilenanfang entspricht, um die Liste zu erstellen.
GitHub fügt den Headern der Readme- Datei automatisch Identifikationen hinzu . Die Identifikationen werden aus dem Headernamen generiert und die Bindestriche (-) ersetzen die Leerzeichen. Sie eignen sich hervorragend für die Navigation im Inhaltsindexanker. Wenn die Datei readme.md auf einer anderen Plattform verwendet werden soll, die Headern nicht automatisch Identifikationen zuweist, kann die Ankernavigation mithilfe von HTML generiert werden:
## Table of Contents <a name="general-info"></a> ### General Info
Dem Index folgen die jeweiligen Inhaltsblöcke der einzelnen Abschnitte:
## 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 
Die allgemeinen Informationen des Projekts sind wichtig, um sich über die kurze Erklärung hinaus ein Bild davon zu machen. Mit Markdown können Sie auch Grafiken, Screenshots oder andere Bilder in Ihre Dokumentation einfügen. Schreiben Sie dazu einfach ein beschreibendes Wort in Klammern, gefolgt von der URL des Bildes in Klammern (ohne verschachtelte Leerzeichen). Stellen Sie ein Ausrufezeichen davor, damit 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
Mit dem Markdown-Format können Sie eine nicht nummerierte Liste mit einem Sternchen (*) am Zeilenanfang aufschreiben.
Links können an einer beliebigen Stelle in die Datei readme.md eingefügt werden . Die Vorgehensweise ist der einer Bilddatei sehr ähnlich, nur ohne das Ausrufezeichen am Zeilenanfang. Setzen Sie das zu verknüpfende Wort in Klammern, gefolgt vom Pfad zur Website, ebenfalls in Klammern (und ohne verschachtelte Leerzeichen).
Die Datei muss sich immer im selben Repository befinden. Sie können auch andere öffentlich zugängliche Dateien verwenden, aber dann besteht die Gefahr, dass der Eigentümer sie irgendwann löscht und Ihre readme.md- Dateien 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 Readme- Dateien häufig im Zusammenhang mit der Entwicklung von Computerprogrammen verwendet werden, ist es hilfreich, Quellcodebeispiele in das Dokument aufzunehmen . Markdown hat zu diesem Zweck auch eine Formatierungsoption. Sie können den Code am Anfang und am Ende mit drei gravierenden Akzenten (“ ”) formatieren. Sie können die Codepassagen auch direkt in den Text einfügen.
## 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.
A?>? Am Anfang der Zeile wird der Text in ein Anführungszeichen umgewandelt.
## 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 |
Eine Kombination aus geordneten und ungeordneten Listen kann auch in der Datei readme.md verwendet werden . Dazu müssen Sie nur die nummerierte Liste mit der entsprechenden Nummer fortsetzen.
Als Beispiel haben wir fett und kursiv geschriebene Wörter und Textabschnitte integriert . Sie können kursiv schreiben, indem Sie ein einzelnes Sternchen (*) oder einen Unterstrich (_) vor oder nach dem betreffenden Wort oder Textabschnitt setzen. Doppelte Sternchen oder Unterstriche werden für die fette Markierung verwendet.
Beispiele: Readme-Dateivorlage
Hier sind die Beispiele, die im Artikel noch einmal behandelt werden, diesmal zusammengefasst in Form einer Readme- Dateivorlage :
## 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  ## 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 |
Mit dem WYSIWYG-Editor von Dillinger können Sie ganz einfach eine readme.md- Datei erstellen .