hur man skriver vackra och meningsfulla README.md

Tips för en fantastisk readme-fil (och varför det är viktigt)

19 Jan, 2020 · 6 min läs

vi, utvecklare, är mycket bra med kod och alla små detaljer i våra projekt. Men några av oss (mig ingår) brist på mjuka färdigheter även i online-samhället.,

en utvecklare skulle spendera en timme med att justera stoppning och marginal på en enda knapp. Men skulle inte spara 15 minuter för projektbeskrivningen Readme-filen.

Jag hoppas att de flesta av er redan vet vad en readme.md fil är och vad det används för. Men för nybörjare här ska jag försöka förklara vad det exakt är.

vad är en Readme.md?

README (som namnet antyder: ”Läs mig”) är den första filen man ska läsa när man startar ett nytt projekt., Det är en uppsättning användbar information om ett projekt och en slags handbok. Det är den första filen Github eller någon git hosting webbplats kommer att visa när någon öppnar ditt förråd..

som du tydligt kan se här Readme.md filen är i roten av förvaret och visas automatiskt av github under projektkatalogen.

och.md – tillägget kommer från ett ord: markdown., Det är en markup språk för textformatering. Precis som HTML är det en markup språk för att göra våra dokument presentabel.

här är ett exempel på en markdown-fil och hur den gör på github faktiskt. Jag använder VSCode här för förhandsgranskning som visar en förhandsvisning av markdown filer samtidigt.

åste bo djupt in i språket.

nu ska vi prata affärer., Du spenderade timmar på ett projekt, du gjorde det offentligt på GitHub och du vill ha människor / rekryterare / kollegor / (Ex? se ditt projekt. Tror du verkligen att de skulle gå in i root/src/app/main.js för att se din vackra logik? Allvarligt?

nu när jag har din uppmärksamhet, låt oss se hur man hanterar detta.

skapa dokumentation för dina komponenter

förutom ditt projekts readme är det viktigt att dokumentera dina komponenter för en begriplig kodbas. Det gör det mycket lättare att återanvända komponenter och behålla din kod., Använd verktyg som Bit (Github) för att automatiskt generera dokumentation för komponenter som delas på bit.dev

exempel: söka efter komponenter som delas på Bit.dev

beskriv ditt projekt! (TL;DR)

Skriv en bra beskrivning av dina projekt. Bara för riktlinjer kan du formatera din beskrivning i följande ämnen: –

Titel (en Titelbild också om möjligt…redigera dem på canva.,com om du inte är en grafisk designer.beskrivning (beskriv med ord och bilder)
Demo (bilder, videolänkar, Live Demo länkar)
teknik som används
speciella Gotchas av dina projekt (problem du möter, unika delar av ditt projekt)
Teknisk beskrivning av ditt projekt som – Installation, Installation, hur du bidrar.

låt oss dyka djupt in i tekniker

Jag ska använda detta ett projekt av mig som referens, som jag tror har en av de vackraste readme-filerna jag har skrivit och till och med kom över., Du kan kolla in koden för Readme.md fil här:-

använd pennikonen för att visa markdown-koden: –

lägg till bilder! Snälla!

Du kan ha ett fotografiskt minne men dina läsare kan behöva några faktiska fotografier av demo av ditt projekt.

till exempel gjorde jag ett solitaire-projekt och lade till bilder som en beskrivning i 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

Gif faller i kategorin bilder och github låter dig ha dem på din readme.

märket för ära

märken på din readme ger tittaren en känsla av äkthet., Du kan få anpassade/regelbundet använda sköldar(märken) för ditt förråd från:- https://shields.io

Du kan få personliga sköldar som antalet stjärnor på repo-och kodprocentsindikatorerna också.

Lägg till en Live Demo

om möjligt få ditt projekt värd och skapa en kör demo. Efter att LÄNKA DENNA DEMO TILL DIN README., Du har ingen aning om hur många människor kan sluta leka med dina projekt. Och rekryterare älskar bara levande projekt. Det visar dina projekt är inte bara en soptipp av kod om på github och du faktiskt menar affärer.

Du kan använda hyperlänkar i Readme. Så ge en Live Demo länk strax under titelbilden.

använd kodformatering

Markdown ger Dig möjlighet att formatera text som kod., Så skriv INTE kod som vanlig text istället använd ’ (Tilde) för att slå in koden inuti kodformatering som sådan- var a = 1;

Github ger dig också möjlighet att ange språket koden skrivs in så att den kan använda den specifika textmarkering för att göra koden mer läsbar. För att göra detta använd

”{language-extension}<space>{Code block Inside}”

{ ” }- Triple tilde används för flera rader kod och det låter dig också ange språket för kodblocket.,

With Language Highlighting:-

Without Langage Highlighting:-

Use of HTML

Yes, you can use HTML inside. Not all the features though. But most of it., Även om du bör hålla sig till markdown bara men, vissa funktioner som centring bilder och text i readme är endast möjligt med HTML.

Articles