Sfaturi pentru un minunat fișier readme (și de ce e important)
Noi, dezvoltatorii, sunt foarte bune cu codul și toate detaliile minute de proiectele noastre. Dar unii dintre noi (inclusiv eu) nu au abilități soft chiar și în comunitatea online.,
Un dezvoltator ar petrece o oră ajustând căptușeala și marginea unui singur buton. Dar nu ar fi de rezervă 15 minute pentru descrierea proiectului fișier Readme.
sper ca majoritatea dintre voi deja știu ce o readme.md fișier este și pentru ce se utilizează. Dar pentru începătorii de aici voi încerca să explic ce este exact.
Ce este un Readme.md?
README (după cum sugerează și numele: „citește-mă”) este primul fișier unul ar trebui să citească atunci când începe un nou proiect., Este un set de informații utile despre un proiect și un fel de manual. Este primul fișier Github sau orice site de găzduire Git va apărea atunci când cineva vă deschide depozitul..
după Cum puteți vedea în mod clar aici Readme.md fișier este în rădăcina de depozit și este afișată automat pe github sub directorul de proiect.
și extensia.mdprovine dintr-un cuvânt: markdown., Este un limbaj de marcare pentru formatarea textului. La fel ca HTML este un limbaj de marcare pentru a face documentele noastre prezentabil.
Iată un exemplu de fișier markdown și cum se redă de fapt pe github. Eu folosesc VSCode aici pentru previzualizare care arată o previzualizare a fișierelor markdown simultan.
Aici este un oficial Github foaie de ieftin pentru Markdown format dacă aveți nevoie pentru a locui adânc în limbă.
acum să vorbim de afaceri., Ai petrecut ore întregi într-un Proiect, l-ai făcut public pe GitHub și vrei oameni/recrutori/colegi/(Ex?) a se vedea proiectul. Chiar crezi că ar intra în root/src/app/main.js pentru a vedea acea logică frumoasă a ta? Serios?
acum că v-am atras atenția, să vedem cum să abordăm acest lucru.
generarea documentației pentru componentele dvs.
În plus față de readme-ul proiectului dvs., documentarea componentelor dvs. este crucială pentru o bază de cod inteligibilă. Aceasta face mult mai ușor să reutilizați componentele și să vă mențineți codul., Utilizați instrumente precum Bit (Github) pentru a genera automat documentația pentru componentele partajate pe bit.dev
descrieți proiectul dvs.! (TL; DR)
scrieți o descriere bună a proiectelor dvs. Doar pentru linii directoare, puteți formata descrierea în următoarele subiecte: –
- Titlu (o imagine de titlu prea, dacă este posibil…editați-le pe canva.,com dacă nu sunteți un designer grafic.)
- Descriere(Descrie prin cuvinte și imagini la fel)
- Demo(Imagini, Video, link-uri, Live Demo link-uri)
- Tehnologii Utilizate
- Speciale Chestii de proiecte (Probleme cu care se confruntă, elemente unice de proiect)
- Descrierea Tehnică a proiectului dumneavoastră ca – Instalare, Configurare, Modul de a contribui.
să ne aruncăm adânc în detalii tehnice
voi folosi acest proiect al meu ca referință, care cred că are unul dintre cele mai frumoase fișiere readme pe care le-am scris și chiar le-am întâlnit., Puteți verifica codul din fișierul Readme.md fișier aici:-
Utilizare pe pictograma creion pentru a arăta cod reduceri :-
ADĂUGAȚI IMAGINI! Te rog!
este posibil să aveți o memorie fotografică, dar cititorii dvs. ar putea avea nevoie de câteva fotografii reale ale demo-ului proiectului dvs.de exemplu, am făcut un proiect solitaire și am adăugat imagini ca descriere în 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-uri se încadrează în categoria de imagini și github permite să le aveți pe readme.
Insigna de Onoare
insignele de pe readme oferă privitorului o anumită senzație de autenticitate., Puteți obține personalizate/folosit cu regularitate scuturi(insigne) pentru depozitul din:- https://shields.io
puteți obține personalizate scuturi, cum ar fi numărul de stele de pe repo și codul procentuale a indicatorilor de asemenea.
adăugați un Demo Live
dacă este posibil, găzduiți-vă proiectul și configurați un demo care rulează. După aceea, conectați această demonstrație la README., Nu ai nici o idee cât de mulți oameni s-ar putea termina în jurul valorii de joc cu proiectele tale. Și recruiter iubesc doar proiecte live. Acesta arată proiectele dvs. nu sunt doar o groapa de cod de stabilire pe github și tu de fapt înseamnă afaceri.
puteți folosi Hyperlink-uri în Readme. Deci, da un link live Demo chiar sub imaginea din titlu.
utilizați formatarea codului
Markdown vă oferă opțiunea de a formata textul ca cod., Deci, nu scrie cod ca text simplu în loc de a folosi ` (Tilda) pentru a încheia acest cod în interiorul cod de formatare ca atare- var a = 1;
Github, de asemenea, vă oferă opțiunea de a specifica limba în care codul este scris în astfel încât să pot folosi anumite evidențierea text pentru a face codul mai ușor de citit. Pentru a face acest lucru folosim
„{limba-extensia}<spațiu>{bloc de Cod în Interiorul}„
{ „ }- Triple tilda este utilizat pentru multi-linie de cod și, de asemenea, vă permite să specificați limba bloc de cod.,
With Language Highlighting:-
Without Langage Highlighting:-
Use of HTML
Yes, you can use HTML inside. Not all the features though. But most of it., Deși ar trebui să rămânem la markdown numai, dar, unele caracteristici cum ar fi centrarea imagini și text în readme este posibilă numai prin HTML.
Lasă un răspuns