See Selgitatud õpetab teile avatud lähtekoodiga projekti dokumentatsiooni kirjutamist. 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.
1
Kirjutage oma projekti pealkiri. Kui kirjutate oma projekti jaoks README-i, peaksite esimese asjana lisama projekti pealkirja. Koos pealkirjaga peaksite lisama ka uusima versiooni numbri ja viimase värskendamise kuupäeva.
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. Saate lisada ka mis tahes erifunktsioonid, ekraanipildid, koodistiilid, kasutatud tehnoloogiad või raamistikud või midagi muud, mis oleks kasutajatele ja arendajatele kasulik.
3
Selgitage oma projekti nõudeid. Kui teie projekt vajab nõuetekohaseks töötamiseks mingeid erinõudeid, lisage need nõuded ja juhised või link nende installimisjuhistele.
4
Kaasake koodi näidis. Esitage selge ja lühike näide selle kohta, milleks teie projekti kasutatakse. Kood peaks olema arendajatel kergesti mõistetav ja API peaks olema selgelt nähtav.
5
Esitage paigaldusjuhised. Selgitage kasutajatele, kuidas tarkvara samm-sammult tööle panna. Teie juhised peaksid olema võimalikult selged. Oletagem, et teie kasutajad ei tea tarkvaraarendusest ega süsteemihaldusest.
6
Selgitage, kuidas tarkvara kasutada. Rääkige inimestele, kuidas oma tarkvarast maksimumi võtta. Esitage samm-sammult juhised nii oma tarkvara kasutamiseks kui ka erinevate konfiguratsioonivalikute ja nende seadistamise kohta.
7
Rääkige kasutajatele, kuidas saada tehnilist abi. Pakub linke mis tahes meililistidele, IRC-kanalitele või kogukonna foorumitele, kust kasutajad saavad tehnilise abi saamiseks pöörduda. Andke ka kogenumatele kasutajatele teada, kuhu projekti paremaks muutmiseks vigu ja ideid esitada. Kui leiate, et saate erinevatelt kasutajatelt palju samu küsimusi, võiksite lisada KKK-d (korduma kippuvad küsimused). projekti dokumentatsioon.
8
Selgitage, kuidas panustada. Kui töötate avatud lähtekoodiga projektiga, andke kasutajatele teada, kuidas nad saavad teie projekti panustada. Selgitage oma standardeid ja andke potentsiaalsetele kaastöölistele mõned juhised.
9
Loetlege krediidid. Anna krediiti alati seal, kus krediit tuleb tasuda. Loetlege kindlasti kõigi kaastöötajate nimed ja lingid mis tahes kolmandate osapoolte teekide või programmide juurde, mida olete kasutanud. Lisage lingid mis tahes inspiratsioonile, mis teil võib olla projekti koostamisel.
10
Esitage oma kontaktandmed. Inimesed võivad soovida teiega ühendust võtta mitmel põhjusel. Esitage kindlasti kehtiv e-posti aadress, mida inimesed saavad teiega ühenduse võtmiseks kasutada. Mõned riigid võivad seadusega nõuda lisateavet, näiteks postiaadressi või ettevõtte nime.
11
Esitage litsentsi teave. Kasutajate jaoks on oluline teada, kuidas teie projekti litsentsitakse. Veebis on palju standardlitsentse, mida saate kasutada. Selgitage, millist litsentsi teie projekt kasutab, samuti mis tahes kolmanda osapoole raamatukogude või programmide litsentse, mida võite kasutada. Te ei pea oma dokumentides selgitama kogu litsentsi. Andke kasutajatele lihtsalt teada, millist litsentsi teie projekt kasutab, ja lisage link litsentsi täieliku teabe juurde.
12
Loetlege kõik projekti versioonid. Looge kindlasti loend kõigist oma projekti varasematest versioonidest ja kirjutage lühikirjeldus selle kohta, milliseid muudatusi iga versiooni jaoks tegite.