See wikiHow õpetab teile, kuidas kirjutada avatud lähtekoodiga projekti dokumentatsiooni. Seda dokumentatsiooni nimetatakse tavaliselt README -failiks. README on teksti- või HTML -dokument, mis sisaldab teie projekti kohta olulist teavet nii kasutajatele kui ka arendajatele.
Sammud
Samm 1. Kirjutage oma projekti pealkiri
Kui kirjutate oma projektile README, peaksite esmalt lisama projekti pealkirja. Pealkirja juurde peaksite lisama ka uusima versiooni numbri ja viimati uuendatud kuupäeva.
Samm 2. Kirjutage oma projekti kirjeldus
Järgmine asi, mille peate oma README -sse lisama, on teie projekti lühikirjeldus. Selgitage, mida projekt teeb, miks see eksisteerib ja milliseid probleeme see lahendab. Võite lisada ka kõik erifunktsioonid, ekraanipildid, koodistiili, kasutatud tehnoloogia või raamistiku või mis tahes muu, mis oleks kasutajatele ja arendajatele kasulik.
Samm 3. Selgitage oma projektiga seotud nõudeid
Kui teie projekt vajab nõuetekohaseks toimimiseks mingeid erinõudeid, loetlege kindlasti need nõuded ja juhised või link nende paigaldamise juhistele.
Samm 4. Lisage koodi näidis
Esitage selge ja kokkuvõtlik näide sellest, milleks teie projekti kasutatakse. Kood peaks olema arendajatele lihtne aru saada ja API peaks olema selgelt nähtav.
Samm 5. Esitage paigaldusjuhised
Selgitage kasutajatele, kuidas oma tarkvara samm-sammult vormingus käivitada. Teie juhised peaksid olema võimalikult selged. Oletame, et teie kasutajatel pole teadmisi tarkvaraarendusest ega süsteemihaldusest.
Samm 6. Selgitage, kuidas tarkvara kasutada
Rääkige inimestele, kuidas oma tarkvarast maksimumi võtta. Pakkuge samm-sammult juhiseid oma tarkvara kasutamiseks, samuti erinevaid konfiguratsioonivõimalusi ja nende seadistamist.
Samm 7. Öelge kasutajatele, kuidas tehnilist abi saada
Pakub linke mis tahes meililistidele, IRC kanalitele või kogukonna foorumitele, kuhu kasutajad saavad tehnilise abi saamiseks pöörduda. Samuti andke kogenumatele kasutajatele teada, kuhu projekti parandamiseks vigu ja ideid esitada.
Kui leiate, et saate erinevatelt kasutajatelt palju samu küsimusi, võiksite projekti dokumentatsiooni osaks lisada KKK (korduma kippuvad küsimused)
Samm 8. Selgitage, kuidas panustada
Kui töötate avatud lähtekoodiga projekti kallal, andke oma kasutajatele teada, kuidas nad saavad teie projektile kaasa aidata. Selgitage oma standardeid ja andke potentsiaalsetele kaastöötajatele juhiseid.
Samm 9. Loetlege krediidid
Andke krediiti alati seal, kus krediiti tuleb maksta. Loetlege kindlasti kõigi kaasautorite nimed ja lingid kolmandate osapoolte raamatukogudele või programmidele, mida olete kasutanud. Lisage lingid mis tahes inspiratsioonile, mis teil on olnud projekti loomisel.
Samm 10. Esitage oma kontaktandmed
Inimesed võivad teiega ühendust võtta mitmel põhjusel. Sisestage kindlasti kehtiv e -posti aadress, mida inimesed saavad teiega ühendust võtta.
Mõni riik võib seaduse järgi nõuda lisateavet, näiteks postiaadressi või ettevõtte nime
Samm 11. Esitage litsentsiteave
Kasutajatel on oluline teada, kuidas teie projekti litsentsitakse. Veebis on palju standardlitsentse, mida saate kasutada. Selgitage, millist litsentsi teie projekt kasutab, samuti mis tahes kolmandate osapoolte raamatukogude või programmide litsentse, mida võite kasutada.
Te ei pea dokumentides kogu litsentsi selgitama. Andke kasutajatele lihtsalt teada, millist litsentsi teie projekt kasutab, ja lisage link litsentsi täieliku teabe juurde
Samm 12. Loetlege kõik projekti versioonid
Kindlasti looge oma projekti kõigi varasemate versioonide loend ja kirjutage lühike kirjeldus selle kohta, milliseid muudatusi iga versiooni kohta tegite.
Näpunäiteid
- Hea tava on alustada oma projekti README kirjutamist enne projekti arendamist. See aitab teil oma projekti läbi mõelda ja selle, mida peate saavutama. See aitab teil välja töötada juhiseid, mida saate teistele kaasautoritele edastada, ja olete rohkem motiveeritud oma projekti alguses oma README -faili kirjutama.
- Veenduge, et värskendate oma projektiga töötades sageli oma README -faili ja muud dokumentatsiooni.
- Kui README -fail on pikem kui leht, saate eraldi dokumendina kirjutada pikemad osad, näiteks installijuhised, kasutusjuhendi ja KKK -d. Kindlasti looge sisukord kogu oma projekti dokumentatsioonile ja lisage link README -faili nõuetekohasele dokumentatsioonile.