Tips voor een geweldig readme-bestand (en waarom dat belangrijk is)

/div>

wij, ontwikkelaars, zijn erg goed met code en alle minieme details van onze projecten. Maar sommigen van ons (ik inbegrepen) gebrek aan soft-skills, zelfs in de online gemeenschap.,

een ontwikkelaar zou een uur besteden aan het aanpassen van de opvulling en marge van een enkele knop. Maar zou niet sparen 15 minuten voor het project beschrijving Readme bestand.

Ik hoop dat de meesten van u al weten wat een readme.md bestand is en waarvoor het wordt gebruikt. Maar voor de nieuwelingen hier zal ik proberen uit te leggen wat het precies is.

Wat is a Readme.md?

README (zoals de naam al doet vermoeden:” read me”) is het eerste bestand dat gelezen moet worden bij het starten van een nieuw project., Het is een set nuttige informatie over een project en een soort handleiding. Het is het eerste bestand dat Github of elke Git hosting site zal laten zien wanneer iemand je repository opent..

zoals u hier duidelijk kunt zien Readme.md het bestand bevindt zich in de root van de repository en wordt automatisch weergegeven door github onder de project directory.

en de.mdextensie komt van een woord: markdown., Het is een opmaaktaal voor tekstopmaak. Net als HTML is het een opmaaktaal om onze documenten toonbaar te maken.

Hier is een voorbeeld van een markdown bestand en hoe het eigenlijk op github wordt weergegeven. Ik gebruik VSCode hier voor preview die een voorbeeld van markdown bestanden tegelijkertijd toont.

Hier is een officiële GitHub Cheat Sheet voor Markdown formaat als je diep in de taal moet blijven.

laten we het nu over zaken hebben., Je hebt uren besteed aan een project, Je maakte het openbaar op GitHub en je wilt mensen / recruiters / collega’s / (Ex?) zie je project. Denk je echt dat ze in root/src/app/main.js zouden gaan om die mooie logica van jou te bekijken? Serieus?

nu ik jullie aandacht heb, laten we eens kijken hoe we dit kunnen aanpakken.

documentatie genereren voor uw componenten

naast de readme van uw project is het documenteren van uw componenten cruciaal voor een begrijpelijke codebase. Het maakt het veel gemakkelijker om componenten te hergebruiken en je code te onderhouden., Gebruik tools zoals Bit (Github) om automatisch documentatie te genereren voor componenten gedeeld op bit.dev

voorbeeld: zoeken naar onderdelen gedeeld op Bit.dev

Beschrijf uw project! (TL; DR)

Schrijf een goede beschrijving van uw projecten. Alleen voor richtlijnen, kunt u uw beschrijving formatteren in de volgende onderwerpen:-

  • Titel (ook een Titelafbeelding indien mogelijk…bewerk ze op canva.,com als je geen grafisch ontwerper.)
  • beschrijving (beschrijven door woorden en afbeeldingen)
  • Demo (Afbeeldingen, Video links, Live Demo links)
  • gebruikte technologieën
  • speciale Gotcha ‘ s van uw projecten (problemen die u ondervond, unieke elementen van uw project)
  • Technische Beschrijving van uw project zoals – installatie, Setup, Hoe bij te dragen.

laten we dieper ingaan op technische details

Ik ga dit ene project van mij als referentie gebruiken, waarvan ik denk dat het een van de mooiste readme-bestanden heeft die ik heb geschreven en zelfs tegenkwam., U kunt de code van de Readme.md bestand hier:-

gebruik het potloodpictogram om de afwaarderingscode te tonen :-

<

afbeeldingen toevoegen! Alsjeblieft!

u kunt een fotografisch geheugen hebben, maar uw lezers hebben mogelijk enkele echte foto ‘ s van de demo van uw project nodig.

bijvoorbeeld, Ik heb een solitaire project gemaakt en afbeeldingen toegevoegd als een beschrijving in de readme.,

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.,

GIF ‘ s vallen in de categorie van afbeeldingen en github laat je ze op je readme.

de Badge of Honour

Badges op uw readme geven de kijker een gevoel van authenticiteit., U kunt custom/regelmatig gebruikt schilden(badges) voor uw archief:- https://shields.io

U kunt voor persoonlijke schilden, zoals het aantal sterren op de repo-en code percentage indicatoren ook.

voeg een live Demo toe

indien mogelijk laat uw project gehost worden en stel een lopende demo in. LINK daarna deze DEMO naar je README., Je hebt geen idee hoeveel mensen zouden kunnen eindigen spelen rond met uw projecten. En recruiter houdt gewoon van live projecten. Het toont uw projecten zijn niet alleen een dump van code leggen op github en je eigenlijk meent zaken.

u kunt hyperlinks gebruiken in uw readme. Dus geef een Live Demo link net onder de titel afbeelding.

Gebruik Code-opmaak

Markdown geeft u de optie om tekst als code op te maken., Schrijf dus geen code als platte tekst in plaats daarvan gebruik ` (Tilde) om de code als zodanig in code opmaak te wikkelen- var a = 1;

Github geeft je ook de optie om de taal waarin de code is geschreven op te geven, zodat het de specifieke tekstmarkering kan gebruiken om de code leesbaarder te maken. Gebruik hiervoor

“‘{language-extension}<spatie{Code block Inside} ` `

{” ` } – Triple tilde wordt gebruikt voor code met meerdere regels en het laat u ook de taal van het code block specificeren.,

With Language Highlighting:-

Without Langage Highlighting:-

Use of HTML

Yes, you can use HTML inside. Not all the features though. But most of it., Hoewel je moet vasthouden aan markdown alleen maar, sommige functies zoals Centreren van afbeeldingen en tekst in de readme is alleen mogelijk door HTML.

Articles

Geef een reactie

Het e-mailadres wordt niet gepubliceerd. Vereiste velden zijn gemarkeerd met *