So schreiben Sie eine README-TXT-Datei: Eine kurze Anleitung von jemandem, der das schon erlebt hat

Ehrlich gesagt kann das Erstellen einer gut strukturierten README-Datei im TXT-Format langweilig und eintönig erscheinen, aber glauben Sie mir, es ist super wichtig, wenn Sie Ihren Datensatz oder Ihr Projekt tatsächlich mit anderen teilen möchten. Ich war schon einmal in der Situation, dass ich Rohdaten hatte, keine Erklärung und keine Ahnung, was was ist, und das hat später nur Chaos verursacht. Hier ist also eine unkomplizierte Methode, um eine anständige README-Datei zusammenzustellen – nichts Besonderes, nur genug Informationen, damit jemand anderes (oder Ihr zukünftiges Ich) versteht, worum es geht.

Öffnen Ihres Texteditors: Das Ganze starten

Nehmen Sie zunächst den Texteditor zur Hand, mit dem Sie am besten zurechtkommen. Unter Windows funktioniert Notepad, aber für fortgeschrittene Benutzer reicht Notepad++, oder halten Sie es einfach – TextEdit auf dem Mac im Nur-Text-Modus. Linux? Wahrscheinlich gedit, nano oder was auch immer in Ihrer Distribution ist. Ehrlich gesagt habe ich auch schon vim verwendet, was für Anfänger aber etwas übertrieben ist.Öffnen Sie ihn jedenfalls; Sie geben hier nur die grundlegenden Informationen ein – keine Formatierung oder Rich Text erforderlich. Einfach nur einfacher Text. Speichern Sie es unter README.txt– machen Sie deutlich, wohin es gehört. Wenn Sie einen eigenen Ordner für Ihr Projekt haben, speichern Sie die README-Datei dort zusammen mit Ihren Datendateien. Verwenden Sie Datei > Speichern unter und wählen Sie Nur-Text (*.txt). Ganz einfach.

Benennen Sie Ihre README-Datei: Wie soll sie heißen?

Geben Sie ganz oben den Namen Ihres Datensatzes oder Projekts ein – das ist nicht nur ein Platzhalter, sondern der Anker, der alles klar macht. Anstatt es beispielsweise einfach „README“ zu nennen, seien Sie konkreter: Climate_Data_2024.txt. So verlierst du später beim Blättern durch einen Ordner nicht den Überblick. Das mag trivial erscheinen, spart aber jede Menge Denkzeit. Betrachten Sie es als Beschriftung Ihres Werkzeugkastens, damit Sie nicht wahllos Dinge herausziehen, wenn Sie die Wetterdaten tatsächlich benötigen.

Auflistung des Erstellers und aller DOI-Links

Fügen Sie nun eine Liste der Autoren oder Ihres Teams hinzu. Bei einem Einzelprojekt reicht vielleicht nur Ihr Name. Wenn ein DOI vorhanden ist – das ist ein Digital Object Identifier, so etwas wie ein permanenter Link zu den Daten oder der Veröffentlichung – fügen Sie ihn hinzu. Sie erhalten ihn normalerweise aus Repositories wie Zenodo, DataCite oder sogar GitHub. Beispiel: https://doi.org/xx/xxxxx. Durch die Angabe eines DOI lässt sich Ihr Datensatz leicht zitieren und gewinnt an Glaubwürdigkeit, insbesondere wenn andere ihn wiederverwenden. Wenn Sie sich nicht sicher sind, ob Sie das tun sollten, denken Sie einfach: „Wird das später jemand validieren oder zitieren wollen?“ Wenn ja, fügen Sie den DOI hinzu. Und am besten halten Sie es einfach, aber vollständig – niemand möchte raten, wer das zusammengeschustert hat oder woher es stammt.

Hinzufügen von Erstellungs- und letzten Aktualisierungsdaten

Notieren Sie anschließend, wann Sie die README-Datei erstellt und zuletzt aktualisiert haben. Sie können das Datum manuell eingeben – z. B.25.04.2024 – oder, wenn Sie es etwas aufwendiger mögen, Kommandozeilentools verwenden, um es zu generieren. Unter Mac/Linux beispielsweise der dateBefehl oder unter Windows PowerShell.Get-DateAber ehrlich gesagt funktioniert es auch gut, es einfach einzutippen. Diese Information ist wirklich nützlich, insbesondere wenn Sie Datensätze oder Dokumentationen regelmäßig aktualisieren. Es ist gut, auch zu erwähnen, ob es eine neuere Version zugehöriger Dateien gibt, damit die Benutzer wissen, dass sie die neuesten Informationen lesen. Wenn Ihr Datensatz regelmäßig aktualisiert wird, sollten Sie zur Vereinfachung eine Versionsnummer wie v1.0 oder einen Hinweis „zuletzt aktualisiert“ hinzufügen. Das ist nichts Besonderes, hilft aber, spätere Verwirrungen zu vermeiden.

Dokumentieren von Variablen, Begriffen oder Datenspalten

Hier bin ich endlich etwas ins Detail gegangen: Listen Sie alle Variablen, Merkmale oder Schlüsselbegriffe in den Daten auf. Seien Sie dabei sehr beschreibend. Wenn Ihr Datensatz beispielsweise Temperaturen protokolliert, geben Sie an, ob es sich um Celsius oder Fahrenheit handelt – z. B.Temperatur (°C). Dasselbe gilt für andere Messungen: Druck, Luftfeuchtigkeit, pH-Wert usw. Wenn Sie sich nicht sicher sind, was ein Begriff bedeutet oder welche Einheiten verwendet werden, markieren Sie ihn mit einem Fragezeichen, z. B.pH-Wert [?]. So wissen künftige Benutzer oder sogar Sie selbst später, dass Sie es noch einmal überprüfen müssen. Wenn Ihre Daten außerdem bestimmte Koordinatensysteme oder Referenzrahmen verwenden – wie WGS84 für geografische Daten – fügen Sie diese Informationen hinzu. Bonuspunkte gibt es, wenn Sie für jede Variable ein kurzes Beispiel angeben, damit klar ist, welche Art von Werten zu erwarten sind.

---

Alles in allem macht diese Art von Vorlage Ihre README zu mehr als nur einer leeren Seite. Sie ist eine schnelle Anleitung für jeden (und ehrlich gesagt auch für Ihr zukünftiges Ich), um zu verstehen, was drin ist und wie es zusammengestellt wurde. Ich gebe zu, ich habe ein paar Anläufe gebraucht, um herauszufinden, wie viele Details ich hinzufügen und wo ich das letzte Aktualisierungsdatum platzieren sollte, ohne es zu überladen. Aber selbst mit einer einfachen Textdatei herumzuspielen ist besser, als einfach alles undokumentiert zu lassen – glauben Sie mir.

Ich hoffe, das hat geholfen – ich habe viel zu lange gebraucht, um alles herauszufinden. Viel Glück und viel Spaß beim Dokumentieren! Zumindest ist es besser als die vage „README“, die ich wochenlang ignoriert habe.

---

---