Faceți un README
sugestii pentru un README bun
fiecare proiect este diferit, deci luați în considerare care dintre aceste secțiuni se aplică dvs. Secțiunile utilizate în șablon sunt sugestii pentru majoritatea proiectelor open source. De asemenea, rețineți că, în timp ce un README poate fi prea lung și detaliat, prea lung este mai bun decât prea scurt. Dacă credeți că README-ul dvs. este prea lung, luați în considerare utilizarea unei alte forme de documentație, mai degrabă decât tăierea informațiilor.
nume
alegeți un nume care se explică automat pentru proiectul dvs.,
descriere
spuneți oamenilor ce poate face proiectul dvs. în mod specific. Oferiți context și adăugați un link către orice referință cu care vizitatorii ar putea să nu fie familiarizați. O listă de caracteristici sau o subsecțiune de fundal poate fi, de asemenea, adăugată aici. Dacă există alternative la proiectul dvs., acesta este un loc bun pentru a lista factorii de diferențiere.
Insigne
pe unele READMEs, este posibil să vedeți imagini mici care transmit metadate, cum ar fi dacă toate testele trec sau nu pentru proiect. Puteți utiliza scuturi pentru a adăuga unele la README. Multe servicii au, de asemenea, instrucțiuni pentru adăugarea unei insigne.,
Visuals
în funcție de ceea ce faceți, poate fi o idee bună să includeți capturi de ecran sau chiar un videoclip (veți vedea frecvent GIF-uri în loc de videoclipuri reale). Instrumente precum ttygif vă pot ajuta, dar consultați Asciinema pentru o metodă mai sofisticată.
instalare
într-un anumit ecosistem, poate exista un mod comun de a instala lucruri, cum ar fi utilizarea Fire, NuGet sau Homebrew. Cu toate acestea, luați în considerare posibilitatea ca oricine citește README-ul dvs. să fie un novice și ar dori mai multe îndrumări., Listarea pașilor specifici ajută la eliminarea ambiguității și îi determină pe oameni să utilizeze proiectul dvs. cât mai repede posibil. Dacă rulează doar într-un context specific, cum ar fi o anumită versiune de limbaj de programare sau un sistem de operare sau are dependențe care trebuie instalate manual, adăugați și o subsecțiune cerințe.
utilizare
utilizați exemple din belșug și afișați rezultatul așteptat dacă puteți. Este util să aveți în linie cel mai mic exemplu de utilizare pe care îl puteți demonstra, oferind în același timp link-uri către exemple mai sofisticate dacă sunt prea lungi pentru a fi incluse în mod rezonabil în README.,
suport
spuneți oamenilor unde pot merge pentru ajutor. Poate fi orice combinație a unui tracker de probleme, a unei camere de chat, a unei adrese de e-mail etc.
foaie de parcurs
Dacă aveți idei pentru versiuni în viitor, este o idee bună să le listați în README.
Contribuirea
indicați dacă sunteți deschis la contribuții și care sunt cerințele dvs. pentru a le accepta. pentru persoanele care doresc să facă modificări la proiectul dvs., este util să aveți o documentație despre cum să începeți., Poate că există un script pe care ar trebui să îl ruleze sau unele variabile de mediu pe care trebuie să le stabilească. Faceți acești pași explicit. Aceste instrucțiuni ar putea fi, de asemenea, utile pentru sinele tău viitor.
de asemenea, puteți documenta comenzi pentru a scame codul sau a rula teste. Acești pași ajută la asigurarea unei calități ridicate a codului și la reducerea probabilității ca modificările să rupă din greșeală ceva. A avea instrucțiuni pentru rularea testelor este util mai ales dacă necesită configurare externă, cum ar fi pornirea unui server Selenium pentru testarea într-un browser.,
autori și confirmare
arată aprecierea față de cei care au contribuit la proiect.
Licență
pentru proiecte open source, spune cum este licențiat.
starea proiectului
Dacă ați rămas fără energie sau timp pentru proiectul dvs., puneți o notă în partea de sus a README spunând că dezvoltarea a încetinit sau sa oprit complet. Cineva poate alege să furculiță proiectul sau voluntar să-și intensifice în calitate de întreținător sau proprietar, permițând proiectului să continue. De asemenea, puteți face o solicitare explicită pentru întreținători.