README fajl

Upustvo za pisanje README fajla

24 септембра, 2020

README fajl je nešto sa čime ste se kao developer do sada sigurno već susreli, pa verujemo da ste u praksi naučili kako napisati README fajl.  No, bez obzira da li već imate iskustva ili ste početnik, u ovom tekstu ćemo predstaviti kratko upustvo za pisanje README fajla.

Šta je README fajl?

Ukratko, to je pisano uputstvo koje objašnjava na koji način da instalirate i podesite i koristite neku novu aplikaciju. Iako je namena ovog fajla vrlo jasna i generacije developera su ga pisale uz svoje aplikacije, nažalost ne postoji neki standard koji bi se odnosio na tačan sadržaj fajla. U principu svaki developer može da ga napiše na način kako to njemu odgovara, ali ipak postoje neka osnovna pravila iz dobre prakse koji je dobro pridržavati se.

Zato ćemo mi u ovom tekstu dati neke osnovne smernice koje smatramo korisnim prilikom kreiranja README fajla. Ujedno ćemo objasniti šta bi on sve trebalo da sadrži.

Format

README fajl može biti napisan u bilo kom tekstualnom formatu koji želite. Može to biti plain text, markdown, ili bilo kji drugi format po vašem nahođenju. Naša preporuka je markdown prosto zato što je na taj način lako kreirati dokument bez posebnog editora, a da pritom dokument lepo izgleda i bude lak za čitanje.

Naslov projekta

Posmatrano čisto marketinški, dobro je da naslov vašeg projekta bude jednostavan i da direktno komunicira poruku korisniku. Pored toga potrebno je da iz samog naslova bude odmah jasno o čemu se radi. Kakvu god aplikaciju predstavljate, važno je da iza samog naslova u README fajlu, nakon znaka : bude njen opis iz kojeg je jasna njena namena i funkcija. Recimo da je u pitanju aplikacija za kalibraciju složenih matematičkih modela. U tom slučaju primer dobrog i intuitivnog naziva bi bio CaliMath Mode: Alat za kalibraciju kompleksnih matematičkih modela.

Opis projekta i aplikacije

Ova sekcija treba da sadrži opis projekta, programa ili aplikacije i sve to treba da stane u maksimalno 30 reči. To je zapravo ukratko opisana namena projekta i tehnologije na kojoj je on baziran. Na našem primeru kalibracije složenih matematičkih modela, primer dobrog opisa bi mogao da izgleda otprilike ovako: CaliMath Mode je veb aplikacija bazirana na MathLab platformi, čija je osnovna namena pomoć inženjerima prilikom projektovanja infrastrukturnih projekata u građevinarstvu. Aplikacija omogućava kreiranje i praćenje modela u realnom vremenu.

U suštini opis treba da bude sažet, jasan i da sadrži što više informacija o aplikaciji u okviru predviđenog limita reči. Poželjno je izbeći bilo kakvu formu marketinga u opisu i fokusirati se na prethodno navedene elemente.

Preduslovi za instalaciju / rad sa aplikacijom

Ukoliko vaš projekat zahteva neku određenu hardversku konfiguraciju, odnosno minimum hardverskih resursa za pokretanje ili rad sa aplikacijom, onda je to potrebno navesti u ovoj sekciji. Nije potrebno previše objašnjenja. Jednostavno samo navedite koja je preporučena konfiguracija po komponentama: CPU, RAM, HDD/SSD, GPU… itd.

Na primer: Preporučena min. konfiguracija: CPU 2GHz, 4GB RAM, 1GB HDD/SSD. Internet konekcija sa SSL-om.

Ako je potrebno dodajte i posebne zahteve (ako postoje) po pitanju prava pristupa bazi podataka i slično.

Instalacija

Očekivano, ova sekcija opisuje proces instalacije vezano za vaš projekat. Opciono možete  napraviti INSTALL.md fajl i iz ove sekcije napraviti referencu na njega, pogotovo ako je za opis procesa instalacije potrebno malo više reči.

Kao i do sada trudite se da budete kratki i jasni, bez previše nepotrebnih opisa.  Na primer to može da izgleda nekako ovako: Pokrenite Install.sh fajl kao root fajl da biste instalirali fajlove, podesite pristupe za veb direktorijume, importujte SQL CaliMath_Mode.sql fajl, a zatim obrišite sve nepotrebne instalacione fajlove. Za više informacija pročitajte INSTALL.md fajl.

Samo se pobrinite da uputstvo bude jasno i da ne izostavite nijedan korak. Znate i sami da pogrešno ili nepotpuno uputstvo može da bude prilično frustrirajuće iskustvo.

Način upotrebe

U ovoj sekciji treba da obezbedite osnovne informacije o načinu na koji se korisiti aplikacija za određene konkretne potrebe.

Na primer:

$ ./install.sh -uroot -pP@$$w0rd

Realno, primer može biti jednostavan kao ovaj iznad, ali mođete po potrebi navesti i više primera za različite potrebe i namene.

Saradnja

Ovde naravno možete navesti način na koji potencijalni saradnici na projektu mogu da vas kontaktiraju i eventualno doprinesu unapređenju samog projekta. To može biti i u formi liste ispravki (errata) koje mogu biti dostavljene autoru ili prezentovane na neki drugi način. Na primer može izgledati ovako:

Ukoliko želite da date svoj doprinos ovom projektu, za više informacija pročitajte CONTRIBUTING.md.

To je važno, jer mnogi developeri žele da doprinesu nekom dobrom projektu, pa je dobro da znaju na koji način mogu to da urade.

Autori

U ovoj sekciji navedite sve autore projekta. Opciono uključite i kontakt podatke i godinu u kojoj je autor bio aktivan na projektu. Na primer: Petar Petrović (2019).

Licence

Navođenje licence je neka vrsta standarda u README fajlu. Postoji nekoliko opcija licenciranja koje možete odabrati. Ukoliko niste sigurni koje opcije sve postoje, možete se informisati ovde.

Recimo, to može izgledati ovako: CaliMath Mode je licenciran u skladu sa GPL 3.0.

Zahvalnost

U ovoj sekciji je važno pomenuti sve one koji su aktivno učestvovali u vašem projektu. To je način da im se javno zahvalite na njihovom doprinosu. Na primer: Hvala Jovanu Jovanoviću iz kompanije mCloud.

Zaključak

Na kraju možemo zaključiti da ukoliko se bavite izradom aplikacija za javnu upotrebu, trebalo bi uz svaku aplikaciju uvek da obezbedite i README fajl. Nemojte ostavljati korisnike u nedoumici kako da instaliraju i koriste vašu aplikaciju. Potrudite se da kreirate neku vrstu vašeg standarda korsiteći neke osnovne smernice koje smo dali u ovom tekstu. Za detaljnije uputstvo za pisanje README fajla, posetite www.makeareadme.com

Da li i na koji način vi pišete svoj README fajl? Podelite sa nama svoja iskustva i opišite ukratko standard kojeg se vi držite prilikom njegovog kreiranja.

Bez komentara

Оставите одговор

Ваша адреса е-поште неће бити објављена. Неопходна поља су означена *