Tips til en fantastisk readme-filen (og hvorfor det er vigtigt)
Vi udviklere, er meget godt med kode og alle de mindste detaljer af vores projekter. Men nogle af os (mig inkluderet) mangler i bløde færdigheder, selv i online-samfundet.,
en udvikler ville bruge en time på at justere polstring og margin på en enkelt knap. Men ville ikke spare 15 minutter for projektbeskrivelsen Readme fil.
Jeg håber, at de fleste af jer allerede ved, hvad en readme.md filen er, og hvad det bruges til. Men for nybegynderne her vil jeg forsøge at forklare, hvad det præcist er.
hvad er en Readme.md?
README (som navnet antyder: “Læs mig”) er den første fil, man skal læse, når man starter et nyt projekt., Det er et sæt nyttige oplysninger om et projekt og en slags manual. Det er den første fil Github eller enhver Git hosting site vil vise, når nogen åbner din repository..
Som du tydeligt kan se her over Readme.md fil i roden af arkivet, og der vises automatisk ved github under projektet bibliotek.
og.mdudvidelse kommer fra et ord: markdo .n., Det er et markeringssprog til tekstformatering. Ligesom HTML er det et markeringssprog at gøre vores dokumenter præsentable.
Her er et eksempel på en markdo .n fil, og hvordan det gør på github faktisk. Jeg bruger VSCode her for preview, der viser et uddrag af markdown-filer samtidigt.
Her er en officiel Github cheat sheet til Markdown-format, hvis du har brug for at dvæle dybt ind i sproget.
lad os nu tale forretning., Du har brugt timer på et projekt, du har offentliggjort det på GitHub, og du vil have folk/rekrutterere/kolleger / (eks?) se dit projekt. Tror du virkelig, at de ville gå ind i root/src/app/main.js for at se din smukke logik? Seriøst?
nu hvor jeg har fået din opmærksomhed, lad os se, hvordan man tackler dette.
generering af dokumentation for dine komponenter
ud over dit projekt readme, dokumentere dine komponenter er afgørende for en forståelig kodebase. Det gør det meget nemmere at genbruge komponenter og vedligeholde din kode., Brug værktøjer som Bit (Github) til automatisk at generere dokumentation for komponenter, der deles på bit.dev
beskriv dit projekt! (TL; DR)
Skriv en god beskrivelse af dine projekter. Bare for retningslinjer, kan du formatere din beskrivelse i følgende emner: –
- Titel (en titel billede også hvis det er muligt…redigere dem på canva.,com hvis du ikke er en grafisk designer.)
- Beskrivelse(Beskriv med ord og billeder både)
- Demo(Billeder, Video, links, Live Demo links)
- Teknologier, der Anvendes
- Specielle Fælder af dine projekter (Problemer, du står overfor, unikke elementer af dit projekt)
- Teknisk Beskrivelse af dit projekt, som – Installation, Opsætning, Hvordan du kan bidrage.
lad os dykke dybt ind i teknikaliteter
Jeg vil bruge dette ene projekt som reference, som jeg synes har en af de smukkeste readme-filer, jeg har skrevet og endda stødt på., Du kan checke koden ud af Readme.md-fil her:-
Brug blyant-ikonet for at vise den markdown-kode :-
TILFØJ BILLEDER! Kom nu!
Du har muligvis en fotografisk hukommelse, men dine læsere har muligvis brug for nogle faktiske fotografier af demoen til dit projekt.for eksempel lavede jeg et kabaleprojekt og tilføjede billeder som en beskrivelse 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 ‘ er falder i kategorien af billeder, og github giver dig mulighed for at få dem på din readme.
æresmærket
Badges på din readme giver seeren en vis følelse af ægthed., Du kan få brugerdefineret/bruges regelmæssigt skjolde(badges) til dit arkiv fra:- https://shields.io
Du kan få personlig skjolde såsom antallet af stjerner på repo og kode procent indikatorer for.
Tilføj en Live Demo
Hvis det er muligt få dit projekt vært og oprette en kørende demo. Efter at linke denne DEMO til din README., Du har ingen ID.om, hvor mange mennesker der kan ende med at lege med dine projekter. Og recruiter bare elsker levende projekter. Det viser, at dine projekter ikke kun er et dump af kode, der ligger på github, og du betyder faktisk forretning.
Du kan bruge Hyperlinks i din Readme. Så giv et Live Demo-link lige under titelbilledet.
brug Kodeformatering
Markdo .n giver dig mulighed for at formatere tekst som kode., Så du skal ikke skrive kode som almindelig tekst i stedet bruge ` (Tilde), for at pakke kode inde kode formatering som sådan- var a = 1;
Github også giver dig mulighed for at angive det sprog koden er skrevet i, så det kan anvende den specifikke tekst, der fremhæver at gøre koden mere læsbar. For at gøre dette skal du bruge
“{language-e .tension}<space>{Code block Inside}“
{ “ }- Triple tilde bruges til multi-line kode, og det giver dig også mulighed for at angive sproget for kodeblokken.,
With Language Highlighting:-
Without Langage Highlighting:-
Use of HTML
Yes, you can use HTML inside. Not all the features though. But most of it., Selvom du kun skal holde dig til markdo .n, men nogle funktioner som centrering af billeder og tekst i readme er kun muligt af HTML.
Skriv et svar