Ky wikiHow ju mëson se si të shkruani dokumentacion për një projekt me burim të hapur. Ky dokumentacion zakonisht referohet si një skedar README. README është një tekst ose dokument HTML që përmban informacione të rëndësishme për përdoruesit dhe zhvilluesit në lidhje me projektin tuaj.
Hapa
Hapi 1. Shkruani titullin për projektin tuaj
Kur shkruani një README për projektin tuaj, gjëja e parë që duhet të përfshini është titulli i projektit. Së bashku me titullin, duhet të përfshini edhe numrin e versionit të fundit dhe datën kur është përditësuar për herë të fundit.
Hapi 2. Shkruani një përshkrim të projektit tuaj
Gjëja tjetër që duhet të përfshini në README është një përshkrim i shkurtër i projektit tuaj. Shpjegoni se çfarë bën projekti, pse ekziston dhe cilat probleme zgjidh. Ju gjithashtu mund të përfshini çdo veçori të veçantë, pamje të ekranit, stilin e kodit, teknologjinë ose kornizën e përdorur, ose ndonjë gjë tjetër që do të ishte e dobishme për përdoruesit dhe zhvilluesit.
Hapi 3. Shpjegoni çdo kërkesë që ka projekti juaj
Nëse projekti juaj ka nevojë për ndonjë kërkesë të veçantë në mënyrë që të funksionojë siç duhet, sigurohuni që të rendisni ato kërkesa dhe udhëzime, ose një lidhje me udhëzimet se si t'i instaloni ato.
Hapi 4. Përfshini një mostër të kodit
Jepni një shembull të qartë dhe konciz se për çfarë përdoret projekti juaj. Kodi duhet të jetë i lehtë për t’u kuptuar nga zhvilluesit dhe API duhet të jetë qartë i dukshëm.
Hapi 5. Jepni udhëzimet e instalimit
Shpjegojuni përdoruesve se si të funksionojë softueri juaj në një format hap pas hapi. Udhëzimet tuaja duhet të jenë sa më të qarta. Supozoni se përdoruesit tuaj nuk kanë njohuri për zhvillimin e softuerit ose administrimin e sistemit.
Hapi 6. Shpjegoni se si të përdorni softuerin
Tregojuni njerëzve se si të përfitojnë sa më shumë nga softueri juaj. Jepni udhëzime hap pas hapi se si të përdorni softuerin tuaj, si dhe opsione të ndryshme konfigurimi dhe si t'i vendosni ato.
Hapi 7. Tregojuni përdoruesve se si të marrin ndihmë teknike
Ofron lidhje me çdo listë postale, kanale IRC ose forume të komunitetit të cilave përdoruesit mund t'u drejtohen për ndihmë teknike. Gjithashtu njoftoni përdoruesit më me përvojë se ku të paraqesin defekte dhe ide për ta bërë projektin më të mirë.
Nëse zbuloni se po merrni shumë nga të njëjtat pyetje nga përdorues të ndryshëm, mund të dëshironi të përfshini një FAQ (pyetje të shpeshta) si pjesë e dokumentacionit të projektit tuaj
Hapi 8. Shpjegoni se si të kontribuoni
Nëse jeni duke punuar në një projekt me burim të hapur, njoftoni përdoruesit tuaj se si mund të kontribuojnë në projektin tuaj. Shpjegoni çdo standard që keni dhe jepni disa udhëzime për kontribuesit e mundshëm.
Hapi 9. Listoni kreditet
Gjithmonë jepni kredi aty ku duhet të merret kredia. Sigurohuni që të rendisni emrat e të gjithë kontribuesve, si dhe lidhjet me ndonjë bibliotekë ose program të palëve të treta që mund të keni përdorur. Përfshini lidhje me çdo frymëzim që mund të keni pasur gjatë ndërtimit të projektit tuaj.
Hapi 10. Jepni informacionin tuaj të kontaktit
Njerëzit mund të duan të lidhen me ju për çfarëdo arsye. Sigurohuni që të jepni një adresë të vlefshme emaili që njerëzit mund të përdorin për t'ju kontaktuar.
Disa vende mund të kërkojnë informacion shtesë, siç është adresa postare, ose emri i kompanisë me ligj
Hapi 11. Siguroni informacion për licencën
Usersshtë e rëndësishme që përdoruesit të dinë se si po licencohet projekti juaj. Ka shumë licenca standarde në internet që mund t'i përdorni. Shpjegoni se çfarë licence po përdor projekti juaj, si dhe licencat e bibliotekave ose programeve të palëve të treta që mund të përdorni.
Nuk keni nevojë të shpjegoni të gjithë licencën në dokumentacionin tuaj. Thjesht njoftoni përdoruesit se çfarë licence po përdor projekti juaj dhe siguroni një lidhje me informacionin e plotë të licencës
Hapi 12. Listoni të gjitha versionet e projektit
Sigurohuni që të krijoni një listë të të gjitha versioneve të mëparshme të projektit tuaj dhe shkruani një përshkrim të shkurtër të ndryshimeve që keni bërë për secilin version.
Këshilla
- Practiceshtë praktikë e mirë të filloni të shkruani skedarin tuaj README para se të filloni të zhvilloni projektin tuaj. Kjo do t'ju ndihmojë të mendoni përmes projektit tuaj dhe çfarë keni nevojë për të arritur. Do t'ju ndihmojë të zhvilloni udhëzime që mund t'i komunikoni me kontribuesit e tjerë, dhe do të jeni më të motivuar për të shkruar skedarin tuaj README në fillim të projektit tuaj.
- Sigurohuni që të përditësoni shpesh skedarin tuaj README dhe dokumentacionin tjetër shpesh ndërsa punoni në projektin tuaj.
- Nëse skedari README është më i gjatë se një faqe ose më shumë, mund të shkruani seksionet më të gjata, të tilla si udhëzimet e instalimit, udhëzuesit e përdoruesit dhe FAQ si një dokument i veçantë. Sigurohuni që të krijoni një tabelë të përmbajtjes për të gjithë dokumentacionin e projektit tuaj dhe siguroni një lidhje me dokumentacionin e duhur në skedarin README.