Tips for en kjempeflott readme-filen (og hvorfor det er viktig)

Jan 19, 2020 · 6 min lese

Vi, utviklere, er veldig bra med kode og alle de små detaljene i våre prosjekter. Men noen av oss (meg inkludert) mangel på soft-ferdigheter, selv i internett-samfunn.,

En utbygger ville bruke en time justere padding og margin på en enkelt knapp. Men ville ikke spare 15 minutter for prosjektet beskrivelse Readme-filen.

jeg håper de fleste av dere allerede vet hva en readme fil.md-fil er, og hva det brukes mot. Men for nybegynnere her skal jeg prøve å forklare hva det egentlig er.

Kva er ein Viktig.md?

README (som navnet antyder: «les meg») er den første filen bør man lese når du starter et nytt prosjekt., Det er et sett av nyttig informasjon om et prosjekt og en slags manual. Det er den første filen Github eller noen Git hosting nettstedet vil vises når noen åpner depotet..

Som du kan tydelig se over her Viktig.md-fil i roten av depotet og vises automatisk av github nedenfor prosjektet katalogen.

Og.mdextension kommer fra et ord: markdown., Det er et markup-språk for tekst-formatering. Akkurat som HTML-det er et markup-språk for å gjøre våre dokumenter presentabel.

Her er et eksempel på en markdown filen, og hvordan det gjør på github faktisk. Jeg bruker VSCode her for forhåndsvisning, som viser en forhåndsvisning av markdown-filer samtidig.

Her er en offisiell Github jukse ark for Markdown-format hvis du trenger å bo dypt inn i språket.

la oss Nå snakke forretninger., Du brukte flere timer på et prosjekt, du gjorde det offentlige på GitHub, og du vil personer/rekrutterere/kolleger/(Ex? se prosjektet ditt. Tror du virkelig de ville gå inn root/src/app/main.js for å vise at vakre logikken din? Seriøst?

Nå som jeg har din oppmerksomhet, la oss se hvordan de skal takle dette.

Generere dokumentasjon for dine komponenter

I tillegg til prosjektet er viktig, dokumentere dine komponenter er avgjørende for en forståelig codebase. Det gjør det mye enklere å gjenbruke komponenter og vedlikeholde kode., Bruk verktøy som Bit (Github) til auto-genererer dokumentasjon for komponenter som er delt i biter.dev

Eksempel: søke etter komponenter delt på Bit.dev

Beskrive ditt prosjekt! (TL;DR)

Skriv en god beskrivelse av dine prosjekter. Bare for retningslinjene, kan du formatere din beskrivelse i følgende emner:-

  • Title (Tittel Bilde for hvis det er mulig…Redigere dem på canva.,com hvis du ikke er en grafisk designer.)
  • Beskrivelse(Beskriv med ord og bilder som er likt)
  • Demo(Bilder, Video, linker, Live Demo lenker)
  • Teknologi som Brukes
  • Spesielle mest profesjonelle veldrevne av dine prosjekter (Problemene du står overfor, unike elementer av prosjektet)
  • Teknisk Beskrivelse av prosjektet som – Installasjon, Oppsett, Hvordan du kan bidra.

La oss dykke dypt inn i tekniske

jeg skal bruke dette ett prosjekt av meg som en referanse, som jeg tror har en av de vakreste readme-filer som jeg har skrevet, og selv kom over., Du kan sjekke ut de etiske Viktig.md-fil her:-

Bruk blyant-ikonet for å vise markdown-kode :-

LEGG til BILDER! VÆR så snill!

Du kan ha et fotografisk minne, men leserne kan trenge litt faktiske bilder av den demo av prosjektet.

For eksempel, gjorde jeg en kabal prosjektet og lagt til bilder 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

HAHA… Got ya Github.,

Gif faller inn i kategorien av bilder og github lar du har dem på din viktig.

Merke av Ære

Navneskilt på readme gi betrakteren noen følelse av autentisitet., Du kan få tilpassede/regelmessig brukte skjold(merker) for depotet fra:- https://shields.io

Du kan få personlig skjold som antall stjerner på repo og kode prosentandel indikatorer for.

Legge til En Live Demo

Hvis mulig få prosjektet vert og sett opp en kjører demo. Etter at KOBLINGEN DENNE DEMOEN TIL README., Du har ingen anelse om hvor mange personer som kan ende opp med å spille rundt med dine prosjekter. Og rekrutterer bare ELSKER live prosjekter. Det viser prosjektene er ikke bare en dump av koden liggende på github, og du faktisk mener business.

Du kan bruke Hyperlenker i din Viktig. Så gi en Live Demo link rett under tittelen Bilde.

Bruk Koden Formating

Markdown gir deg muligheten til å formatere tekst som kode., Så du trenger ikke å skrive koden som ren tekst i stedet bruk » (Tilde) for å bryte koden inne kode formatering som sådan- var a = 1;

Github gir deg også muligheten til å angir språk koden er skrevet i, slik at det kan bruke bestemte uthevet tekst for å gjøre koden mer lesbar. For å gjøre dette bruker

«{språk-extension}<plass>{Kode blokk Inne}«

{ « }- Trippel tilde er brukt for multi-line-koden og den gjør også at du angir språk koden blokk.,

With Language Highlighting:-

Without Langage Highlighting:-

Use of HTML

Yes, you can use HTML inside. Not all the features though. But most of it., Selv om du bør holde deg til markdown bare men, noen funksjoner som sentrering bilder og tekst i readme-er bare mulig ved hjelp av HTML.