Tipps für eine tolle readme-Datei (und warum das wichtig ist)

Jan 19, 2020 · 6 min read

Wir, die Entwickler, sind sehr gut mit code und die kleinsten details unserer Projekte. Aber einige von uns (ich eingeschlossen) Mangel an Soft-Skills auch in der Online-Community.,

Ein Entwickler würde eine Stunde damit verbringen, das Auffüllen und den Rand einer einzelnen Schaltfläche anzupassen. Aber würde nicht 15 Minuten für die Projektbeschreibung Readme-Datei ersparen.

Ich hoffe die meisten von euch wissen schon was ein readme.md datei ist und wofür sie verwendet wird. Aber für die Neulinge, hier werde ich versuchen zu erklären, was es genau ist.

Was ist eine Readme-Datei.md?

README (wie der name schon sagt: „lies mich“) ist die erste Datei, die man Lesen sollte wenn Sie ein neues Projekt beginnen., Es ist eine Reihe nützlicher Informationen zu einem Projekt und eine Art Handbuch. Es ist die erste Datei, die Github oder eine andere Git-Hosting-Site anzeigt, wenn jemand Ihr Repository öffnet..

Wie Sie hier deutlich sehen können Readme.md die Datei befindet sich im Stammverzeichnis des Repositorys und wird automatisch von github unter dem Projektverzeichnis angezeigt.

Und die.mdErweiterung kommt von einem Wort: markdown., Es ist eine Markup-Sprache für die Textformatierung. Genau wie HTML ist es eine Auszeichnungssprache, um unsere Dokumente präsentabel zu machen.

Hier ist ein Beispiel für eine Markdown-Datei und wie sie tatsächlich auf Github gerendert wird. Ich verwende hier VSCode für die Vorschau, die gleichzeitig eine Vorschau von Markdown-Dateien anzeigt.

Hier ist ein offizieller Github-Spickzettel für das Markdown-Format, wenn Sie wohnen Sie tief in der Sprache.

Jetzt reden wir über das Geschäft., Sie haben stundenlang an einem Projekt gearbeitet, es auf GitHub veröffentlicht und möchten Personen/Personalvermittler/Kollegen / (Ex?) siehe Ihr Projekt. Glauben Sie wirklich, dass sie in root/src/app/main.js gehen würden, um diese schöne Logik von Ihnen zu sehen? Ernsthaft?

Nun, da ich Ihre Aufmerksamkeit habe, lassen Sie uns sehen, wie das anzugehen.

Dokumentation für Ihre Komponenten generieren

Neben der Readme Ihres Projekts ist die Dokumentation Ihrer Komponenten entscheidend für eine verständliche Codebasis. Es macht es viel einfacher, Komponenten wiederzuverwenden und Ihren Code zu pflegen., Verwenden Sie Tools wie Bit (Github), um automatisch Dokumentation für auf Bit gemeinsam genutzte Komponenten zu generieren.dev

Beispiel: die Suche nach Komponenten, die gemeinsam auf Etwas.dev

Beschreiben Sie Ihr Projekt! (TL;DR)

Schreiben Sie eine gute Beschreibung Ihrer Projekte. Nur für Richtlinien können Sie Ihre Beschreibung in die folgenden Themen formatieren: –

  • Titel (wenn möglich auch ein Titelbild…Bearbeiten Sie sie auf canva.,com, wenn Sie kein Grafikdesigner sind.)
  • Beschreibung (Beschreiben durch worte und bilder gleichermaßen)
  • Demo (Bilder, Video links, Live Demo links)
  • Technologien Verwendet
  • Spezielle Gotchas von ihre projekte (Probleme sie konfrontiert, einzigartige elemente von ihr projekt)
  • Technische Beschreibung von ihr projekt wie – Installation, Setup, Wie zu beitragen.

Lassen Sie uns tief in die technischen Details eintauchen

Ich werde dieses eine Projekt von mir als Referenz verwenden, das meiner Meinung nach eine der schönsten Readme-Dateien hat Ich habe geschrieben und bin sogar darauf gestoßen., Sie können den Code des überprüfen Readme.md datei hier:-

Verwenden Sie das Stiftsymbol, um den Markdown-Code anzuzeigen: –

HINZUFÜGEN BILDER! BITTE!

Sie kann haben ein fotografisches Gedächtnis, sondern Ihre Leser müssen möglicherweise einige aktuelle Fotos von der demo Ihres Projekts.

Zum Beispiel habe ich ein Solitär-Projekt erstellt und Bilder als Beschreibung in der Readme hinzugefügt.,

Now you may want to add a video description of your projects too. Just like I did. BUT… Github doesn’t let you add a video to the readme… So… So what?

…WE USE GIFS

HAHA… Got ya Github.,

Gifs fallen in die Kategorie der Bilder und mit github können Sie sie in Ihrer Readme-Datei haben.

Das Abzeichen der Ehre

Abzeichen auf Ihrer Readme geben dem Betrachter ein Gefühl von Authentizität., Sie können benutzerdefinierte/regelmäßig verwendete Schilde(Abzeichen) für Ihr Repository erhalten von:- https://shields.io

Sie können personalisierte Schilde wie die Anzahl der Sterne auf dem Repo und Code Prozentsatz Indikatoren zu erhalten.

Fügen Sie eine Live-Demo hinzu

Wenn möglich holen Sie sich Ihr Projekt und richten Sie eine laufende Demo ein. Danach VERLINKEN SIE DIESE DEMO AUF IHRE README., Sie haben keine Ahnung, wie viele Leute am Ende mit Ihren Projekten herumspielen könnten. Und Recruiter lieben einfach Live-Projekte. Es zeigt, dass Ihre Projekte nicht nur ein Dump von Code sind, der auf Github liegt, und Sie meinen es tatsächlich ernst.

Sie können Hyperlinks in Ihrer Readme verwenden. Geben Sie also einen Live-Demo-Link direkt unter dem Titelbild an.

Verwenden Sie Code Formating

Markdown gibt Ihnen die Möglichkeit, Text als Code zu formatieren., Schreiben Sie also keinen Code als Klartext, sondern verwenden Sie ` (Tilde), um den Code in die Codeformatierung als solche einzuschließen- var a = 1;

Github gibt Ihnen auch die Möglichkeit, die Sprache anzugeben, in die der Code geschrieben ist, damit er die spezifische Texthervorhebung verwenden kann, um den Code lesbarer zu machen. Verwenden Sie dazu

` ‚ {language-extension}<space{Codeblock Inside} ` `

{“ ` } – Triple Tilde wird für mehrzeiligen Code verwendet und Sie können auch die Sprache des Codeblocks angeben.,

With Language Highlighting:-

Without Langage Highlighting:-

Use of HTML

Yes, you can use HTML inside. Not all the features though. But most of it., Sie sollten sich zwar nur an Markdown halten, aber einige Funktionen wie das Zentrieren von Bildern und Text in der Readme-Datei sind nur über HTML möglich.