See peaks sisaldama kõiki aspekte, mida arendaja peab teadma ja mida ei ole võimalik saada otse kood. Need sisaldavad arendusdokse ja -kohustusi, täielikke kasutuselevõtu juhiseid, välise integratsiooni kirjeldusi jne. See postitus juhendab teid võimsa, ilusa ja loetava README-faili loomisel oma projekt.

Hea sissejuhatus hästi ettevalmistatud projektidokumentatsiooni jaoks on leitav githubi juhenditest: https://guides.github.com/features/wikis/. See sätestab, et "README peaks sisaldama ainult vajalikku teavet, et arendajad saaksid alustada projekti kasutamist ja panustamist".

Seda silmas pidades tutvustame nimekirja komponentidest ja parimatest tavadest, mida me Codestis järgime projektdokumentatsiooni loomisel.

Kiire sissejuhatus

- Projekti pealkiri: see on iga README'i jaoks hädavajalik.

- Staatusmärgid: kui te kasutate mingeid väliseid koodikvaliteedi mõõtmisi, automatiseeritud testimist või muid vahendeid, on dokumendi alguses hea koht, kus näidata teistele, kas need töötavad.

- Kirjeldus: lisage paar lauset projekti kohta, et kirjeldada kiiresti selle põhieesmärki ja tegevust.

Sisukord

Sisukorra loetelu võib olla kasulik pikkade dokumentatsioonifailide puhul, kuid kui teie README on üsna lühike, siis ei ole see vajalik.

Üldine teave

- Umbes jagu: see peaks olema projekti üksikasjalikum kirjeldus - see võib sisaldada teavet kasutajate ja nende rollide kohta, mõningaid keerulisemaid juhtumeid, ekraanipilte jne.

- Maketid: UI/UX mudeli ressursside lingid, kui neid on olemas.

• Muu teave nagu Juurdepääs serveritele või Integratsioon väliste APIdega: näiteks staging instance url-aadress, jagatud mittetundlikud (!) juurdepääsutunnused, lingid dokumentatsioonile, mõned juhised jne.

Paigaldamine

- Nõuded: eeltingimused, mis peavad olema täidetud enne rakenduse seadistamise alustamist, nt väliste tööriistade paigaldamine.

- Seadistamine: samm-sammuline juhend, mida järgida, et projekt käivitada ja käivitada.

- Seadistused: kirjeldavad, kuhu kohalikud seaded salvestatakse, ja annavad juhiseid, kuidas oma seaded kätte saada.

- Kohalik konfiguratsioon: kui on mõned juhtumid kohaliku seadistamise jaoks, siis on see hea koht selgitamiseks.

Arendus

See jaotis on ideaalne koht selliste juhiste jaoks nagu funktsioonide arendamine, veaparandused, hotfixid, ühised funktsioonid, testimine, stiilijuhendid, koodi korraldamine, muud projektis kasutatavad arendusvahendid (nt valvurid või dokkerid) jne. Ärge unustage mainida kõiki reegleid, mida iga meeskond liige peaks teadma.

Kasutuselevõtmine

Andke iga keskkonna jaoks selged samm-sammulised juhised ja kõik, mida on "hea teada" kasutuselevõtu tegemisel.

Muud ideed eraldi sektsioonide jaoks

- API dokumentatsioon

- Changelog

- Välised ressursid: koht igasuguste linkide jaoks, mis võivad olla kasulikud.

- Rakenduste virna: projektis kasutatava rakenduste virna nimekiri - võib sisaldada lühikirjeldust ja teenusepakkuja nime.

Meeskond

On vaieldav, kas on vaja näidata praeguseid projektimeeskonna liikmeid (github pakub vaikimisi täielikku panustajate nimekirja), kuid alati on tore, kui näed oma nime ühe projekti autorina. Kui te seda teete, hoidke see võimalikult ajakohane.

Viimased sõnad

Pidage meeles: iga projekt on ainulaadne ja nii on ka selle dokumentatsioon. README-i kirjutamiseks ei ole olemas ühte head lahendust. Lihtsalt järgige üldisi näpunäiteid ja kõige tähtsam on alati meeles pidada refaktooringut, mis on samuti seotud README-ga. Alati on hea mõte vaadata dokumenti kui tervikut ja mõelda see ümber, kui midagi on vaja teistmoodi kuvada.

Veel üks asi: "juhised" on võtmetähtsusega, seega kirjutage neid palju. Aitäh!

Loe edasi:

• Avatud-suletud põhimõte. Kas ma pean seda kunagi kasutama?
• Kuidas kirjutada head ja kvaliteetset koodi?
• Vuelendar. Uus Codesti projekt, mis põhineb Vue.js-l.