Autor: Davor Tvorić, Frontend Engineer at Productive
Pisanje dokumentacije je važno, ali i naporno. Vjerujem da smo svi svjesni da je potrebno voditi dokumentaciju tijekom razvoja produkta. Ne znam kako se vi osjećate, ali kada ja pišem dokumentaciju, automatski dobijem glavobolju.
Nije niti stvar u tome da je toliko teško (većinu vremena), nego je problem to što cijeli proces može biti zamoran. Volim pisati, ali čak se i ja moram nagovarati da napišem nekoliko rečenica o tome što sam napravio. But you gotta do it, baby!
Objasnit ću vam načine koje smo uveli kako bismo poboljšali proces vođenja dokumentacije. Ako je to nešto s čim se mučite, siguran sam da ćete moći izvući neke korisne ideje iz ovog članka.
Problemi s dokumentacijom
Neću trošiti previše vremena u pojašnjavanju koncepta dokumentacija, zašto je bitna i kome, jer sam siguran da nas većina to već zna. Prijeći ću odmah na konkretne probleme koji mogu nastati kod pisanja dokumentacije.
Kada sam počeo raditi u Productiveu, već je postojala povelika količina dokumentacije. Dosta stvari i procesa je bilo zapisano, od postavljanja računala do detalja o korištenju specifične komponente. Bilo mi je uzbudljivo što ću saznati sve o svemu, ali sam ubrzo došao do slučajeva i značajki koji nisu bili dovoljno detaljni ili koji nisu uopće bili zapisani. Ovo me nije toliko iznenadilo budući da se radi o velikom proizvodu u kojem stvarno ima svačeg. Ostao sam optimističan — ovo je značilo samo da ću se trebati češće javljati kolegama i neke stvari zaključiti sam.
Nakon nekoliko mjeseci, došlo je vrijeme da ja nešto dokumentiram. Sve do tog trenutka mi je bilo uzbudljivo da ću napisati sve što sam napravio. Međutim, kada je došlo vrijeme da nešto stvarno napišem, pojavio mi se mučan osjećaj. Znao sam da moram to napraviti, ali sada sam morao razmišljati o tome zašto i kako je nešto napravljeno, koliko detaljno trebam nešto objasniti, gdje napisati dokumentaciju, itd. Još je gore kada se radi o sustavu koji ne razumiješ u potpunosti i počneš preispitivati jesi li ti uopće prava osoba za to.
Toliko problema — a nisam još napisao nijednu riječ.
Naše rješenje
Malo dramatiziram, ali sve ove misli su mi prolazile kroz glavu u nekom trenutku. U Productiveu smo osmislili nekoliko ideja kako bismo riješili ove izazove. Kada bismo imali jednostavni proces za pisanje dokumentacije, svima bi ostalo više snage i vremena sjesti i zapravo ju napisati.
Dogovorili smo se da:
- Svi trebamo pisati dokumentaciju
- Ne mora biti savršeno isprva
- Treba biti zapisano sve što iziskuje javljanje kolegama ili dublje istraživanje
- Dokumentaciju treba voditi u kontinuitetu
- Zastarjele dokumente treba pobrisati
- Razvoj treba biti vođen dokumentacijom
Pogledajmo što svaka od ovih točaka predstavlja.
Svi trebamo pisati dokumentaciju
Na ovo sam se morao naviknuti, kao što možda možete iščitati iz mojeg prvog iskustva rada u Productiveu. To ne znači da svatko treba dokumentirati samo nove značajke na kojima je radio, nego i stare koje možda i ne razumije u potpunosti. Uvijek je moguće tražiti pomoć od nekog s više iskustva. Čak i ako nije 100 % točno, drugoj osobi će biti lakše nešto ispraviti nego pronaći vremena i raspisati cijeli dokument. Međutim, bitno je potaknuti iskusnije kolege u pisanju kompliciranijih ili težih dijelova dokumenta jer neke stvari mogu stvarno biti prekomplicirane za shvatiti samostalno.
Ne mora biti savršeno isprva
Ovo se nastavlja na moj prethodni savjet. S obzirom na to da je dokumentaciju potrebno stalno držati ažurnom, u redu je napisati natuknice bez da se previše pazi na gramatiku, strukturu, i cjelovitost teksta. Najbitnije je razviti neometani proces koji će povećati angažman kod članova tima. Uvijek je moguće popraviti tekst kasnije. Također, drugi ljudi mogu lako ostaviti povratnu informaciju na dokumentaciju jer ne moraju u potpunosti razumjeti značajku o kojoj se radi.
Treba zapisati sve što iziskuje javljanje kolegama ili dublje istraživanje
Iako je važno zapisati nove značajke i održavati dokumentaciju o starijima, nemojte zaboraviti na nepotpunu dokumentaciju. Često naiđemo na neki problem koji je dokumentiran, ali nam nedostaje neki specifičan slučaj. To može značiti da nešto krivo radite, ali je svejedno bitno dokumentirati što se dogodilo. Vjerojatno će se nekom dogoditi ista situacija, a tih desetak minuta koje odvojite za zapisivanje im može sačuvati sate istraživanja.
Ovo možemo smatrati procesom „odozdo prema gore”. Umjesto da dokumentiramo cijeli proces ili feature, zapiše se jedan slučaj. Ovo može malo „olakšati” proces jer nije potrebno znati i razumjeti sve detalje o featureu. Zapamtite: bez obzira da li se radi o nekoj temi iz onboardinga ili o nečemu tehničkom, kandidat za dokumentaciju je bilo što može smanjiti zbunjenost na projektu!
Dokumentaciju treba voditi u kontinuitetu
Po mom mišljenju, ovaj korak je najteži. Jednako kao što je CI/CD proces (continuous integration/ continuous deployment) bitan, dokumentacija se treba pisati i voditi iz dana u dan. Ako su proces ili značajka dovoljno bitni, dobar trenutak za dokumentaciju je kada proces ili značajka postanu stabilni. Još bolji trenutak je prije nego što kodiranje započne, ako je to moguće. Pisanje dokumentacije dok su informacije svježe pomaže izgraditi čitavu priču uz širi kontekst, ne samo nepovezane djeliće. Kada se dokumentacija radi nekoliko tjedana kasnije, neki bitni detalji i nijanse iz razvoja se često propuste. To u nekim slučajevima može voditi do nepotpune dokumentacije pa je najbolje riješiti taj problem u korijenu!
Zastarjele dokumente treba obrisati
Zastarjela dokumentacija je gora od dokumentacije koja ne postoji. Kada netko otkrije da nešto ne radi onako kako je navedeno u dokumentaciji, to može dovesti do nedoumica i problema. Ako naiđete na dokumente za koje ste sigurni da su zastarjeli, izbrišite ih da ne zbunjuju druge.
Razvoj treba biti vođen dokumentacijom
Kao što sam već spomenuo, jedan pristup koji razmatramo je pisanje dokumentacije prije nego što kodiranje krene. U praksi smo shvatili da razmatranje featurea prije razvoja može olakšati proces razvoja. To je i dobar način da se uključe članovi tima koji nemaju tehničku podlogu, ali mogu istaknuti probleme i odstupanja prije nego što se ona pretvore u kod.
Zaključak je…
Dokumentacija je vrlo bitna za sve, čak i one koji imaju jako puno iskustva. Bez obzira na to, ponekad nije lako potaknuti sebe ili druge da jednostavno krenete pisati dokumentaciju.
Jedno rješenje je pojednostaviti proces. Možete započeti tako da definirate vrijeme i mjesto za pisanje dokumentacije i uključite čitav tim.
Dok istražujete alate koji mogu biti korisni, nemojte zaboraviti na Productive i naš feature, Docs!
Može biti korisno dodati dokumentaciju kao jedan korak u svakodnevnim procesima, npr. uključivanje dokumentacije u procjenu vremena ili traženje izmjena u dokumentaciji prije pull requesta. Možete tretirati vođenje dokumentacije kao pisanje testova, budući da upotpunjuju jedno drugo. Ovakav proces će sigurno povećati vrijeme da se značajke dovrše, ali dokumentacija je jednako važna kao bilo koji drugi dio razvoja.
Ovakav pristup dokumentaciji je nama izrazito pomogao i pokazao se kao dobra podloga za suradnju i nadograđivanje dokumentacije. Nadam se da će vam ovi mali koraci pomoći da provedete značajna poboljšanja na projektima i u svakodnevnom radu.
