• Zuhause
  • Artikel
  • Warum ein README erstellt wurde, ist zu meinem Lieblingsteil der Entwicklung geworden
Veröffentlicht am 18-02-2019

Warum ein README erstellt wurde, ist zu meinem Lieblingsteil der Entwicklung geworden

Foto von rawpixel auf Unsplash

Geständnis und Auflösung

Früher war mein Ansatz eine totale Verschleppung, und ich würde (wenn überhaupt) bis zum Ende eines Projekts warten, um mich mit der Dokumentation zu befassen. Am Ende eines jeden anständigen Projekts fühlte ich mich überwältigt, an den Anfang von dem zurückzukehren, was ich gebaut hatte, um es gut zu dokumentieren.

Ich fand sogar heraus, dass meine mittelmäßigen Dokumentationsversuche zeitweise fehlgeschlagen sind, einfach weil ich den Kontakt mit dem evolutionären Sachverständnis verloren hatte, das ich im Verlauf des Projekts entwickelt hatte. Dieses evolutionäre Wissen ist wirklich sehr wichtig für die Erfassung, da es die Zutaten für eine genaue Dokumentation darstellt.

In meinen ständigen Bemühungen, schwierige Dinge gut zu machen, habe ich eine gute Dokumentation für meine Projekte erstellt. Es mag zwar langweilig oder beschwerlich klingen, aber ich habe herausgefunden, dass der Beginn jeder neuen Entwicklungsanstrengung mit einer einfachen README-Datei meine Sichtweise auf die Dokumentation völlig verändert hat.

Ich betrachte diesen Ansatz nun als meine eigene Mini-Version von Readme Driven Development. Tatsächlich ist es zu meinem Lieblingsteil der Entwicklung geworden. Okay, das ist vielleicht etwas hyperbolisch, aber dieser Schritt gehört sicherlich zu meinen Lieblingsteilen der Entwicklung. Wenn ich bei einem Projekt die Ziellinie überquere und feststelle, dass die Dokumentation 100% ig auf mich wartet, ist das ein tolles Gefühl!

Warum bin ich so ein Fan der README geworden?

Es ermutigt mich, jedes neue Projekt mit einer Dokumentation zu beginnen.

Wir alle wissen, dass Dokumentation nicht als der glamouröseste Teil des Entwicklerlebens gilt, aber wir können uns wahrscheinlich alle einig sein, wie dankbar wir sind, vorhandene Dokumentation zu finden, wenn wir zum ersten Mal in eine neue Codebasis blicken. Gibt es eine bessere Möglichkeit, sich zu ermutigen, den eigentlichen Code zu dokumentieren, als die Dokumentation zum ersten Commit für Ihr Repo zu machen?

Im Gegensatz zu manchen Entwicklern, die immer mit derselben Art von Codebase arbeiten, weiß ich nicht immer, wie meine Projektverzeichnisstruktur aussehen wird, aber ich weiß genau, dass Dokumentation immer angemessen ist.

In diesen Tagen ist die README meine erste Verpflichtung zu einem neuen Projekt-Repository. Indem ich mich dazu verpflichtet habe, zu Beginn eines Projekts sinnvolle Inhalte in die README einzubringen, kann ich jetzt alles, was ich über das Projekt lerne, einfangen, während ich es lerne.

Und ich spreche nicht nur von einer leeren README-Datei, sodass git add etwas zu tun hat. Ich meine, ein solider erster Stich in echte, aussagekräftige Dokumentation. Ich fange alles ein, was ich über das Projekt weiß, und liste jede Aufgabe auf, die mir einfällt. Es dient als ständiges Mittel, um mein Verständnis des Projekts und der Ergebnisse zu stärken.

Als allgemeine Richtlinie sollten Sie einige einfache Dinge berücksichtigen, die Sie in Ihrem ersten README-Commit in keiner bestimmten Reihenfolge beachten sollten:

  • Termine: Alle wichtigen Termine für dieses Projekt, wie Startdatum, Lieferfrist oder andere wichtige Meilensteintermine.
  • Autor: Das bist du! Geben Sie mindestens Ihren Namen, Ihre Firma (falls zutreffend) und Ihre E-Mail-Adresse an.
  • Referenzinformationen: Alle relevanten Projektlinks, z. B. Problemlisten, Hintergrunddokumentation oder Referenzmaterial für Neulinge des Projekts.
  • Zweck / Ziele: Warum ist dieses Ding ein Projekt? Was ist das Ziel und an welchen Zielen lässt sich Erfolg messen?
  • FAQ: Oft nachträglich, stellen FAQs einige der wichtigsten zu dokumentierenden Dinge dar. Listen Sie so viele auf, wie Sie denken, und erweitern Sie diese Liste dann, wenn neue auftauchen.
  • Konventionen: Weniger üblich, aber alle einzigartigen Konventionen, die andere möglicherweise verstehen müssen, bevor sie einsteigen.
  • Lizenzinformationen: Dies wird wahrscheinlich zu einer echten LICENSE-Datei gehören, die die wichtigsten Details enthält. Es schadet jedoch nie, die Nutzungsbeschränkungen für das im Repository enthaltene geistige Eigentum zu wiederholen.
  • Todos: Eine laufende Liste der Dinge, die abgeschlossen werden müssen, damit dieses Projekt erfolgreich verläuft.

Bonus: Ich kann Markdown verwenden, und Markdown ist fantastisch.

Die allgemeine Konvention für die README-Dokumentation ist Markdown. Wenn Sie Markdown noch nicht verwendet haben, empfehle ich dringend, es zu lernen. Markdown ist eine sehr einfache Möglichkeit, Ihre reinen Textdateien in schön formatierte Dokumentation umzuwandeln. Nur mit Ihrem Texteditor und einigen neuen Syntaxkonventionen können Sie beeindruckende Dokumente erstellen, ohne MS Word oder Google Docs öffnen zu müssen. Das Exportieren von HTML oder PDF ist ebenfalls sehr einfach.

Markdown hat einige wirklich coole Funktionen. Es sind alle wesentlichen Elemente vorhanden: Tabellen, Listen mit Aufzählungszeichen, Hyperlinks, Inline-Bilder, Anker und Lesezeichen, Textformatierung und noch komplexere Dinge wie Flussdiagramme und Diagramme. Erinnern Sie sich an die Todo-Liste, die ich bereits erwähnt habe? Sie können diese als Kontrollkästchen anzeigen und dann abschließen, wenn Sie sie abschließen.

Ich habe gerade die Oberfläche von Markdown gekratzt. Hier finden Sie einige großartige Referenzen, die Ihnen eine bessere Vorstellung davon vermitteln, was Sie erreichen können:

  • Markdown-Tutorial: https://www.markdowntutorial.com
  • GitHub Markdown Guide: https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf
  • Mastering Markdown: https://guides.github.com/features/mastering-markdown/
  • Markdown-Anleitung: https://www.markdownguide.org

Visual Studio Code ist mein bevorzugter Texteditor. Es gibt einige großartige Erweiterungen, die Markdown unterstützen. Mein persönlicher Favorit ist Markdown All In One.

Zum Zeitpunkt der Erstellung dieses Artikels ist es der am meisten heruntergeladene und wird aktiv gewartet. Neben anderen Funktionen bietet es eine Echtzeitvorschau und intuitive Tastenkombinationen. Weitere Visual Studio Code-Erweiterungen mit ähnlichen Funktionen finden Sie hier.

Fazit

Ich bin mir sicher, dass Sie schon einmal dort waren. Wenn Sie sich den Code ansehen, den Sie zu 99% sicher sind, haben Sie noch nie zuvor etwas gesehen, aber Ihr Name steht als Autor darauf. Die Dinge haben immer einen Weg, um wiederzukommen. Immer. Lange nachdem das Projekt abgeschlossen ist, ist es sehr wahrscheinlich, dass die von Ihnen erstellte Dokumentation genauso zu Ihrem Erbe gehört wie der Quellcode selbst.

Wenn Sie nach einem Dokumentationsspiel suchen, empfehle ich Ihnen dringend, Ihr nächstes Projekt mit einer README zu starten. Dieser Ansatz hat mir wirklich geholfen, meine Ergebnisse zu stärken und meine eigenen Projektbeiträge zu verbessern. Selbst wenn Sie es versuchen und es nicht mögen, werden Sie vielleicht zumindest bessere Markdown-Fähigkeiten erhalten. Auch das lohnt die Anstrengung.

Bist du überzeugt Wenn ich Sie sogar teilweise davon überzeugt habe, es zu versuchen, lassen Sie mir bitte ein paar Klatschen. Immer noch nicht überzeugt? Hinterlasst mir einen Kommentar und lasst uns einen Dialog beginnen!

Siehe auch

Wir sind was wir tunRedux Free gehenSo erstellen Sie Ihren ersten witzigen Chatbot mit SAP Conversational AIWie wir unser erstes Flutter-Paket entwickelt habenVorhersage von "Bikeability" in US-amerikanischen Städten