Getty Images/iStockphoto
Wie man eine ansprechende README-Datei anlegt
Entwickler sollten lernen, eine README-Datei zu erstellen, um Kollegen und Kunden mit wichtigen Informationen über ihre Softwareprojekte zu versorgen.
Innerhalb eines Softwareprojekts sind README-Dateien wichtig, da sie als Einstiegspunkt in den Projektcode dienen.
Eine README-Datei ist eine Text- oder Markdown-Datei, die ein Softwareprojekt vorstellt und erklärt. Sie sollte Informationen enthalten, die für Benutzer und Mitwirkende notwendig sind, um das Projekt zu verstehen und mit ihm zu arbeiten.
Der Umfang und Inhalt einer README-Datei kann je nach Projekt, Benutzer und Entwicklerteam variieren. Dennoch gibt es bestimmte Kernkomponenten, die alle README-Dateien gemeinsam haben. Als Entwickler ist es wichtig zu lernen, wie man eine README erstellt, die diese Komponenten auf eine Weise enthält, die am besten zu Ihrem Projekt und Ihrer Organisation passt.
Wie man eine README-Datei erstellt
Planen Sie eine README-Datei, die spezifisch genug ist, um als umfassende Anleitung für neue Entwickler, Administratoren oder sogar Benutzer zu dienen, um das Projekt zu verstehen und mit ihm zu arbeiten. Diese kann allerdings komplex oder wenig praktikabel werden, wenn Sie zu viele Informationen enthält. Es kann einige Zeit dauern, bis Sie den richtigen Grad an Spezifität für Ihr Unternehmen gefunden haben, also scheuen Sie sich nicht, mit Ihrer README zu experimentieren, besonders wenn Ihr Softwareprojekt komplex ist.
Zu den Standard-Tools für die Erstellung einer README-Datei gehören proprietäre und quelloffene Markdown-Editoren wie Visual Studio Code (VS Code) und GitHub Markdown Editor.
Für ein funktionsübergreifendes Team von Mitarbeitern ist es manchmal sinnvoll, die README mit Google Docs oder Microsoft Word zu verfassen und dann die endgültige Version nach der endgültigen Genehmigung in Markdown oder einfachem Text zu veröffentlichen.
Im Folgenden finden Sie eine allgemeine Vorgehensweise für die Erstellung und Veröffentlichung einer README-Datei:
- Beginnen Sie mit einer Standard-README-Vorlage, die den Informationsanforderungen des Projekts entspricht. Ihr Unternehmen sollte die Vorlage in die Bibliothek der Projektartefakte aufnehmen.
- Nennen Sie die Datei README, einen der Industriestandards für solche Dateien. README.md ist zum Beispiel eine README-Datei, die in Markdown erstellt wurde und in GitHub oder GitLab lesbar ist.
- Füllen Sie die README-Vorlage mit dem entsprechenden Inhalt. Verwenden Sie möglichst viele Aufzählungspunkte, Codeblöcke und Tabellen, um die Lesbarkeit zu verbessern und Informationen zu organisieren.
- Legen Sie die README-Datei im Stammverzeichnis des Projekts ab, wenn es sich um ein Softwareprojekt-Repository handelt. Einige SaaS- und Mobile-App-Entwickler, die ihre Dokumentation online veröffentlichen, können ihre README-Datei in den Online-Inhalt integrieren und über ein Anwendungsmenü zugänglich machen.
- Speichern, überprüfen und genehmigen Sie die README-Datei für die Veröffentlichung.
- Übergeben Sie die README-Datei an ein Versionskontroll- oder Content-Management-System und verschieben Sie sie in das ihr zugewiesene Verzeichnis.
Der Prozess zum Erstellen und Veröffentlichen einer README-Datei für eine SaaS-, Cloud- oder mobile Anwendung kann variieren. Nehmen wir zum Beispiel an, dass Ihr Unternehmen DocOps oder eine agile Dokumentationsmethodik in Betracht zieht. In diesem Fall kann sich die README-Datei auf einer separaten Dokumentenseite befinden, die mit der Hauptanwendung verknüpft ist. Für die Erstellung von README-Dateien kann eine Reihe von Tools zum Einsatz kommen, zum Beispiel
- Statische Website-Generatoren, wie Hugo und Jekyll.
- Tools zur Erstellung von Online-Hilfen, wie Adobe RoboHelp oder MadCap Flare.
- Open-Source-Inhaltsverwaltungssysteme, wie Drupal oder WordPress.
SaaS- und Cloud-README-Dateien richten sich häufig an Entwickler und Administratoren und führen sie durch die Cloud-Bereitstellung, die Service-Architektur und die Abhängigkeiten untereinander.
Was sollten Sie in eine README-Datei aufnehmen?
Wenn Sie eine README-Datei für Ihre Anwendungen erstellen, müssen Sie ein Standardformat entwerfen, das das Entwicklungsteam anwendungsübergreifend verwenden kann, und daraus eine Vorlage erstellen. Nehmen Sie sich die Zeit, README-Erstellungsrichtlinien und eine Standardvorlage zu erfassen, damit Entwickler und Produktmanager nicht bei null anfangen müssen. Dokumentierte Standards und eine Vorlage ersparen es den Prüfern, Formatierungs- und Inhaltsänderungen vorzunehmen, die möglicherweise den Rahmen sprengen und Zeit kosten.
Hier sind einige wichtige Komponenten einer README-Datei:
| Komponente | Beschreibung |
| Projekttitel | Die README sollte einen Projekttitel haben. |
| Projektbeschreibung | README-Dateien von Open-Source-Projekten können einen Abschnitt Wie das Projekt gemacht wurde enthalten, der Teil der Projektbeschreibung sein kann. |
| Inhaltsverzeichnis | Ein Inhaltsverzeichnis sollte eine Liste aller wichtigen README-Abschnitte enthalten. |
| Wie man das Projekt installiert | Geben Sie eine klare, schrittweise Anleitung, die es auch jemandem ohne Vorkenntnisse ermöglicht, das Projekt zum Laufen zu bringen, einschließlich Kopieren und Einfügen von freundlichen Befehlszeilenausschnitten. |
| Verwendung | Geben Sie die grundlegenden Befehle mit Beispielen an, um typische Anwendungsfälle für komplexe Tools, wie zum Beispiel eine SaaS-Anwendung, zu demonstrieren. Verweisen Sie auf eine ausführlichere Dokumentation oder Tutorials auf einem Support-Portal. |
| Konfiguration | Wenn Ihr Softwareprojekt konfiguriert werden muss, geben Sie Beispiele für Konfigurationsdateien oder Befehlszeilenargumente an, in denen die Funktion der einzelnen Konfigurationsoptionen erläutert wird (Kopieren und Einfügen). |
| Abhängigkeiten | Führen Sie alle erforderlichen Abhängigkeiten auf und stellen Sie Anweisungen oder ein Skript zu deren Installation bereit. Geben Sie an, ob bestimmte Versionen benötigt werden. |
| Fehlerbehebung | Geben Sie eine Liste der häufigsten Probleme und deren Lösungen an. Für ausführlichere Fehlerbehebungsdokumente verweisen Sie die Benutzer auf Ihr Support-Portal. |
| Mitwirkung | Open-Source-Softwareprojekte enthalten oft diesen Abschnitt, um zu erklären, wie andere zum Projekt beitragen können. |
| Erkenntnisse | Ihre Organisation kann README-Dateien auch verwenden, um Lektionen, die während der Entwicklung des Projekts gelernt wurden, mitzuteilen. |
| Lizenz | Geben Sie die Art der Softwarelizenz an und verweisen Sie auf den vollständigen Lizenztext. Dies ist für Open-Source-Projekte unerlässlich, da immer mehr Unternehmen auf die Softwarelizenzierung ihrer Unternehmenssoftwarekomponenten achten. |
| Kontaktinformationen | Geben Sie spezifische Kontaktinformationen für Support oder weitere Anfragen an, wie zum Beispiel eine E-Mail-Adresse oder einen Link zu Ihrem Support-Portal. |
Best Practices für das Schreiben einer README
Im Folgenden finden Sie einige bewährte Verfahren für das Schreiben einer README-Datei:
- Wie viele technische Dokumente werden auch README-Dateien nicht gelesen. Machen Sie es den Lesern daher leicht, die Dateien zu überfliegen, indem Sie eine einfache Sprache, beschreibende Überschriften und eine logische Struktur verwenden und Fachjargon und komplexe Technologien vermeiden.
- Beginnen Sie die README-Datei mit einem Abschnitt Erste Schritte, der – falls erforderlich – eine Installationsanleitung enthält, die den Kunden Schritt für Schritt erklärt, wie sie die Software sicher und effizient in Betrieb nehmen können.
- Beschreiben Sie alle Sicherheitsmaßnahmen, Authentifizierungsmechanismen und Umgebungskonfigurationen, die der Kunde verstehen oder für eine Cloud- oder SaaS-Anwendung einrichten muss. Diese Dokumentation ist entscheidend für die Aufrechterhaltung der Sicherheit, wenn der Kunde die Anwendung einsetzt.
- Verfolgen Sie einen praktischen Ansatz und geben Sie großzügig Beispiele, wie zum Beispiel Codeschnipsel, Befehlszeilenanweisungen und Anleitungen, die es dem Kunden ermöglichen, Ihre Anwendung in Betrieb zu nehmen.
- Führen Sie alle Abhängigkeitsanforderungen der Software in einem leicht auffindbaren Abschnitt der README-Datei auf.
- Seien Sie großzügig mit Beispielen wie Codeschnipseln und Screenshots, die am besten zeigen, wie die Anwendung zu verwenden ist.
- Geben Sie Links zu Ihrer Dokumentation, Problemdatenbank, Support- und Schulungsinhalten weiter, insbesondere wenn die Anwendung komplex ist.
- Aktualisieren Sie die README-Datei, wenn sich das Projekt weiterentwickelt, indem Sie die Aktualisierung als Aufgabe in den Feature-Release-Lebenszyklus aufnehmen.
Die Erstellung einer README-Datei ist so einfach, wie Ihr Team es macht. Unternehmen, die bei der Erstellung von README-Dateien reaktiv vorgehen, produzieren minderwertige Versionshinweise, da der mit der Entwicklung der README beauftragte technische Redakteur oder Produktmanager mit den konkurrierenden Prioritäten einer Produkteinführung konfrontiert wird. README-Dateien sollten in den Gesamtprojektplan aufgenommen werden – nicht nur in den Dokumentationsplan – mit einem Zeitplan, der Iterationen ermöglicht, um zu vermeiden, dass in den Tagen und Stunden vor der Produktfreigabe in aller Eile eine komplette README von Grund auf geschrieben werden muss.
