Ovaj wikiHow vas uči pisanju dokumentacije za projekat otvorenog koda. Ova dokumentacija se obično naziva README datoteka. README je tekstualni ili HTML dokument koji sadrži važne informacije i za korisnike i za programere o vašem projektu.
Koraci
Korak 1. Napišite naslov svog projekta
Kada pišete README za svoj projekt, prvo što trebate uključiti je naslov projekta. Uz naslov trebate navesti i broj najnovije verzije i datum zadnjeg ažuriranja.
Korak 2. Napišite opis svog projekta
Sljedeća stvar koju trebate uključiti u svoj README je kratak opis vašeg projekta. Objasnite šta projekat radi, zašto postoji i koje probleme rješava. Također možete uključiti sve posebne značajke, snimke zaslona, stil koda, korištenu tehnologiju ili okvir ili bilo što drugo što bi moglo biti korisno korisnicima i programerima.
Korak 3. Objasnite sve zahtjeve koje vaš projekt ima
Ako vašem projektu trebaju neki posebni zahtjevi da bi mogao pravilno funkcionirati, svakako navedite te zahtjeve i upute ili vezu do uputa o tome kako ih instalirati.
Korak 4. Uključite uzorak koda
Navedite jasan i sažet primjer za šta se vaš projekat koristi. Kôd bi programerima trebalo biti lako shvatiti, a API bi trebao biti jasno vidljiv.
Korak 5. Dajte upute za instalaciju
Objasnite korisnicima kako pokrenuti softver u formatu korak po korak. Vaše upute trebaju biti što jasnije. Pretpostavimo da vaši korisnici nemaju znanja o razvoju softvera ili administraciji sistema.
Korak 6. Objasnite kako se koristi softver
Recite ljudima kako da najbolje iskoristite svoj softver. Pružite detaljna uputstva o tome kako koristiti softver, kao i različite mogućnosti konfiguracije i kako ih postaviti.
Korak 7. Recite korisnicima kako da dobiju tehničku pomoć
Pruža veze do bilo koje mailing liste, IRC kanala ili foruma zajednice kojima se korisnici mogu obratiti za tehničku pomoć. Također obavijestite iskusnije korisnike gdje poslati greške i ideje kako bi projekt bio bolji.
Ako otkrijete da od različitih korisnika dobivate mnogo istih pitanja, možda biste trebali uključiti FAQ (često postavljana pitanja) kao dio svoje projektne dokumentacije
Korak 8. Objasnite kako da date svoj doprinos
Ako radite na projektu otvorenog koda, obavijestite svoje korisnike kako mogu doprinijeti vašem projektu. Objasnite sve standarde koje imate i dajte neke smjernice potencijalnim saradnicima.
Korak 9. Navedite kredite
Uvijek dajte kredit tamo gdje kredit dospijeva. Obavezno navedite imena svih saradnika, kao i veze do bilo koje biblioteke ili programa trećih strana koje ste možda koristili. Uključite veze do bilo kakve inspiracije koju ste možda imali pri izgradnji svog projekta.
Korak 10. Navedite svoje kontakt podatke
Ljudi će vas možda htjeti kontaktirati iz raznih razloga. Obavezno navedite važeću adresu e -pošte koju ljudi mogu koristiti da vas kontaktiraju.
Neke zemlje mogu zahtijevati dodatne informacije, poput poštanske adrese ili naziva kompanije prema zakonu
Korak 11. Navedite informacije o licenci
Korisnicima je važno da znaju kako se vaš projekt licencira. Na internetu postoji mnogo standardnih licenci koje možete koristiti. Objasnite koju licencu vaš projekt koristi, kao i licence bilo koje biblioteke ili programa trećih strana koje biste mogli koristiti.
Ne morate objašnjavati cijelu licencu u svojoj dokumentaciji. Samo obavijestite korisnike koju licencu koristi vaš projekt i navedite vezu do potpunih informacija o licenci
Korak 12. Navedite sve verzije projekta
Napravite popis svih prethodnih verzija vašeg projekta i napišite kratak opis izmjena koje ste izvršili za svaku verziju.
Savjeti
- Dobra je praksa započeti pisanje README datoteke prije nego što počnete razvijati svoj projekt. To će vam pomoći da razmislite o svom projektu i šta trebate postići. Pomoći će vam u razvoju smjernica koje možete prenijeti drugim suradnicima, a bit ćete i motiviraniji da napišete svoju datoteku README na početku vašeg projekta.
- Prilikom rada na projektu često ažurirajte svoju datoteku README i drugu dokumentaciju.
- Ako je vaša datoteka README duža od jedne stranice, možete napisati duže odjeljke, kao što su upute za instalaciju, korisnički vodič i FAQ kao zaseban dokument. Svakako stvorite sadržaj za svu projektnu dokumentaciju i pružite vezu do odgovarajuće dokumentacije u datoteci README.