U redu, svima je jasno da za neke kategorije softvera opsežna dokumentacija za korisnike zapravo i nije bitna. Teško da ćete prije početka igranja većine igara ili korištenja nekog antivirusnog softvera prvo pročitati nekoliko desetaka stranica (ili više) uputa, da biste tek nakon toga počeli koristiti program. Prije ćete takav softver početi koristiti onako intuitivno. Međutim, kod poslovno orijentiranih sustava (na primjer, ERP sustava) teško da možete dobiti očekivane rezultate ako prije toga bar malo ne prelistate dijelove priručnika. Ili, u današnje vrijeme nešto uobičajenije, ako ne „proskrolate“ kroz nekoliko stranica uputa u web pregledniku. Ako ni zbog čega drugog, onda zato da pravilno podesite najvažnije postavke programa koje utječu na njegovu uporabu.
Kad već spominjemo prateću dokumentaciju za softver, onda treba spomenuti kako se tu većinom podrazumijeva korisnički orijentirana dokumentacija. Kod svakog malo kompleksnijeg projekta praktično je jednako važna prateća dokumentacija namijenjena samom razvojnom timu. U nju ulaze stvari kao što su popis najvažnijih uočenih problema u trenutnoj verziji, praćenje napredovanja u razvoju trenutne verzije, planovi za buduće smjerove razvoja nove verzije, standardi koji se koriste kod izrade softvera, način testiranja i slično.
Pregled različitih vrsta softverske dokumentacije: Prema https://www.altexsoft.com/.
Zadnja stvar koju ćemo spomenuti u uvodu je to da je dokumentacija tijekom vremena evoluirala od papirnatih oblika, preko čuvanja na posebnim optičkim medijima (CD/DVD) do današnjeg gotovo isključivo elektronskog oblika. Najvažnija prednost novije tehnologije u odnosu na papirnate pretke je svakako u jednostavnosti pretraživanja i pronalaženja potrebnog dijela dokumentacije. A i štamparije mogu malo odahnuti, jer su izgubile važnu kategoriju korisnika.
Oba pogleda na dokumentaciju probat ćemo detaljnije opisati u današnjem tekstu tako da imate svojevrsni vodič za pripremu dokumentacije kod vlastitih projekata. O samom načinu pisanja dokumenata, te alatima koji se pri tome koriste, zbog ograničenog prostora bit će više riječi možda neki drugi put.
Vrste dokumentacije
Iako je najjednostavnije napraviti podjelu dokumentacije na dokumentaciju namijenjenu krajnjim korisnicima i dokumentaciju namijenjenu razvojnim timovima, malo stručnija podjela dokumentacije je nešto složenija. Za detaljan hijerarhijski pregled različitih vrsta dokumentacije možete pogledati prateću sliku uz tekst.
Osnovna podjela dokumentacije za određeni softverski projekt ima sljedeći oblik:
1. Dokumentacija proizvoda
a) Sistemska dokumentacija
b) Korisnička dokumentacija
■ Dokumentacija za krajnje korisnike
■ Dokumentacija za administratore sustava
2. Dokumentacija procesa
U nastavku teksta objasnit ćemo najvažnije dijelove svake od nabrojenih kategorija. U stvarnom svijetu nije za svaki softverski projekt pripremljena baš sva moguća dokumentacija. Pojedini proizvođač softvera sam procjenjuje i bira kakvu dokumentaciju je najvažnije pripremiti na temelju vlastitih razvojnih ili komercijalnih razloga. Primjere pojedinih dijelova dokumentacije možete vidjeti i na pratećim slikama uz ovaj tekst.
Razjasnimo prvo razliku u vrsti dokumentacije na najvišoj razini, to jest razliku između dokumentacije proizvoda i dokumentacije procesa. Dokumentacija proizvoda opisuje sam softverski proizvod koji je već razvijen, te kako se pomoću njega izvode različite operacije. S druge strane, dokumentacija procesa sastoji se od različitih vrsta dokumenata koji opisuju sam postupak (proces) razvoja softvera.
Primjer obrasca za pregled dijelova web sjedišta ili softverskog paketa: Prema izvoru https://venngage.com/blog/site-map-template/.
Već na temelju te osnovne podjele lako je zaključiti kako korisnička dokumentacija (kao veliki dio ukupne dokumentacije proizvoda) opisuje korištenje gotovog proizvoda sa stanovišta korisnika proizvoda. Naravno, u dokumentaciju proizvoda uključena je i dokumentacija namijenjena razvojnim timovima. Dokumentacija procesa je, s druge strane, praktično isključivo posvećena razvojnim timovima. Krajnjeg korisnika vrlo rijetko zanima kako je neki softver razvijen, budući da je prije svega usredotočen na njegovo korištenje. Izuzetak mogu biti slučajevi vanjskog (outsourcing) razvoja softvera, gdje nakon razvoja cjelokupna dokumentacija ide korisniku zbog budućeg organiziranja i upravljanja razvojem novih verzija.
Kad već spominjemo korisničku dokumentaciju, kod složenijih sustava je uobičajena podjela takve dokumentacije na dijelove namijenjene administratorima sustava i dijelove namijenjene krajnjim korisnicima. Na temelju posebno pripremljenih dijelova dokumentacije, administratori sustava konfiguriraju najvažnije parametre sustava za rad, dok ostatak dokumentacije treba podučiti „obične“ korisnike kako koristiti već konfiguriran sustav. Na primjer, administratori sustava na temelju svoje dokumentacije mogu pripremiti ERP sustav tako da pravilno koristi porezne stope, tečajne liste, pisače ili čitače barkodova ili QR kodova, a ostali korisnici koriste već pripremljenu konfiguraciju ERP sustava za svakodnevni rad, koristeći za učenje vlastitu dokumentaciju.
Primjer dokumentiranja zahtjeva za softverske karakteristike: Prema izvoru na web adresi https://www.altexsoft.com/.
Jedan od uobičajenih problema u vezi s korištenjem korisničke dokumentacije je u tome što se u praksi vrlo rijetko može pronaći korisnik koji će prije korištenja programa pročitati cijeli osnovni priručnik. Zato je mnogo bolje, i sa stanovišta korisnika puno produktivnije, pripremiti nekoliko različitih vrsta dokumenata:
1. Vodič za brzi početak
Ovaj dokument bi trebao korisniku ponuditi pregled najvažnijih dijelova softverskog proizvoda i uvod u njegovo korištenje, ali bez detaljnog objašnjavanja kompleksnijih dijelova. Na primjeru ERP sustava to bi značilo da korisnik na temelju takvog dokumenta može početi unositi partnere ili artikle, odnosno pripremati osnovne dokumente, ali neće saznati kako može izvoditi nekakve složene analize poslovnih podataka.
2. Kompletan priručnik
Obuhvaća detaljan pregled korištenja svih dijelova softvera, uključujući i pregled hardverskih i softverskih preduvjeta za njegovo korištenje. Ako se vratimo na prethodni primjer, to je mjesto gdje korisnik može pronaći kako se izvode sve vrste analiza poslovnih podataka u ERP sustavu.
3. Vodič za rješavanje problema
Namijenjen je brzom pronalaženju i rješavanju najčešćih problema s kojima se korisnici susreću u praksi. Važan dio dokumentacije za smanjivanje opterećenja korisničke podrške proizvođača softvera.
4. Različiti interaktivni i video vodiči
Iako nisu obavezni, danas sve više postaju de facto standard u pripremi proširenog oblika korisničke dokumentacije. Velikom broju korisnika je jednostavnije naučiti kako se koristi neki dio softvera na temelju odgovarajućeg video materijala, nego da to probaju naučiti sami isključivo na temelju pisane dokumentacije.
Već smo spomenuli kako je dio korisničke dokumentacije namijenjen posebnoj kategoriji korisnika - takozvanim administratorima sustava. U ovim dijelovima dokumentacije obično se ne opisuje kako djeluje niti kako se koristi softver, već prije svega kako se softver instalira, podešava za rad, te kako se uklanjaju posebni problemi povezani s instalacijom i podešavanjem softvera nakon instalacije. U pravilu je najvažniji dokument iz ove skupine detaljni „Vodič za administratore sustava“, iako se i ovdje mogu pripremiti vodiči za brzi početak te različite video prezentacije o instalaciji ili konfiguriranju različitih dijelova softvera.
Sistemska dokumentacija
Sistemska dokumentacija se nalazi u okviru dokumentacije proizvoda namijenjene razvojnim timovima i kao takva može biti vrlo raznolika. Najčešće veličina takve dokumentacije ovisi o veličini razvojnih timova. Ako je tim velik, onda obično postoje članovi zaduženi samo za izradu i održavanje takve dokumentacije. U tom slučaju onda obično ni svi članovi tima ne poznaju sve dijelove sustava, pa je dobro imati kompleksniju dokumentaciju za njegovo upoznavanje. Ona je i, naravno, odlično polazište za učenje novozaposlenim članovima tima.
Opišimo najvažnije dijelove sistemske dokumentacije:
1. Opis zahtjeva
Predstavlja jedan od temeljnih dokumenata sistemske dokumentacije. U njemu bi prije svega trebalo biti opisano što određeni softver treba raditi. To uključuje navođenje različitih aspekata razvoja softvera, kao što su: ciljevi razvoja, poslovna pravila koja se koriste kod razvoja, potencijalni primjeri korištenja, uloge i odgovornosti pojedinih članova razvojnog tima, različite tehničke i poslovne pretpostavke koje utječu na razvoj, i tako dalje. Jedna od vrlo važnih točaka može biti navođenje onoga što se neće razvijati u trenutnoj verziji, nego će se ostaviti za buduće verzije. Precizno definiranje ove točke može imati vrlo velik utjecaj na datum dovršetka i objave nekog softverskog proizvoda.
2. Dizajn korištenja sustava sa stanovišta korisnika
Ovaj dio dokumentacije prati cjelokupan razvoj softvera, od početnog definiranja zahtjeva, preko samog razvoja i testiranja, pa sve do implementacije i izvođenja operacija nakon implementacije. U okviru ovog dijela dokumentacija se dijeli po fazama u nastajanju softvera, od prikupljanja informacija od osoba za koje se softver razvija, preko pripreme i razumijevanja različitih scenarija kako će korisnici koristiti softver, do „prevođenja“ scenarija u različite dijelove softvera u razvoju. Na primjer, dio ovog dijela dokumentacije je detaljan pregled dijelova web sjedišta ili komponenti softvera u razvoju. U okviru ovog dijela treba detaljno opisati i različite dijelove korisničkog sučelja, te prototipove za njegovo testiranje.
„Wireframe“ za mobilnu aplikaciju: Primjer definiranja korisničkog sučelja za mobilnu aplikaciju https://visme.co/blog/wireframe-examples/.
3. Pregled arhitekture softvera
Za razliku od prethodne vrste dokumentacije gdje je prvenstveno opisano što treba napraviti, u ovom dijelu prije svega treba pripremiti dokumentaciju o tome kako nešto treba napraviti. Za svaku komponentu budućeg sustava treba točno definirati pomoću kojih tehnologija i postupaka se planira izraditi. Također, treba prikazati i kako su sve komponente sustava međusobno povezane. U okviru ovog dijela dokumentacije bilo bi dobro definirati rokove za izradu ključnih dijelova, kako bi se mogao precizno pratiti napredak u razvoju softvera.
4. Dokumentacija izvornog koda
Ovo je najviše tehnički orijentiran dio dokumentacije, namijenjen samim programerima. Iako nije potrebno detaljno opisivati baš svaki dio programskog koda, trebalo bi svakako objasniti kompliciranije dijelove koji bi mogli biti posebno zbunjujući za eventualne buduće članove razvojnog tima.
5. Dokumentacija za osiguravanje kvalitete
Dio dokumentacije koji sadrži različite dijelove povezane s osiguravanjem kvalitete softvera u razvoju. Najvažniji dijelovi povezani su s planiranjem i izvođenjem raznih testova na softveru u različitim fazama njegovog razvoja.
6. API dokumentacija
U novije vrijeme se veliki dijelovi novog softvera pripremaju tako da sadrže različite API funkcije. Budući da se ove funkcije mogu koristiti unutar samog razvojnog tima, ali su često namijenjene i korištenju od strane drugih programera „izvana“, ovaj dio dokumentacije mora biti pripremljen tako da ga razumiju i programeri koji nisu sudjelovali u razvoju API funkcija.
Koios savjetovanje
Goran Novak, voditelj prodaje u uspješnoj hrvatskoj tvrtki Koios savjetovanje d.o.o., otkriva nam kakvu dokumentaciju pripremaju za softverski projekt sa stajališta krajnjeg korisnika i razvojnog tima.
1. Čime se firma točno bavi
Koios se bavi razvojem rješenja unutar nekoliko segmenata koristeći više različitih tehnologija. Prvenstveno razvijamo rješenja za bankarski i financijski sektor, koristeći se najnovijim (npr. blockchain) te nešto starijim tehnologijama, jer ta industrija nije baš poznata kao „early adopter“ za nove stvari. Osim razvoja programskih rješenja, Atlassianovi smo partneri te se bavimo i implementacijama Jira rješenja kod naših korisnika (gdje se jedan dio odnosi baš na ove procese).
2. Kakvu dokumentaciju pripremate za softverski projekt
- sa stanovišta krajnjeg korisnika
Ovisno o samom projektu (ali i o sugovornicima s druge strane), korisnička dokumentacija varira od samih specifikacija i zahtjeva, pa do korisničkih uputa (tipa „how to”). Preferiramo kada su projekti u potpunosti dokumentirani (zahtjevi, planovi, okoline, testovi, očekivanja...), jer nam to uvelike olakšava cjelokupni razvoj – pa i suradnju na samom projektu, ali često to nije baš moguće. Vrlo često to završi samo na dokumentiranju arhitekture, postavljenog sustava i samih uputa korisnicima, što je najmanji dio dokumentacije koji se obavezno isporučuje klijentima.
- sa stanovišta razvojnog tima za praćenje bugova, planiranje i razvoj sljedećih verzija...
Osim dokumentacije koja se razvija zajedno s klijentom, nemamo druge klasične dokumentacije. Naime, sve ostalo pratimo putem specijaliziranih sustava, npr. kod i sve vezano uz kod se prati kroz Bitbucket, bugovi se prate kroz Jira Service Management, planiranje/sprintovi kroz Jira Software. Doduše, dio dokumentacije se ostvaruje i kroz izgradnju same baze znanja, za što koristimo Confluence koji je integriran sa svim prethodnim alatima te na taj način zaokružujemo priču. Postoji još jedan razlog zašto je sve ovo na ovaj način posloženo kod nas, kako smo Atlassianovi partneri te i drugim klijentima pomažemo s ovim procesima, sagledali smo problematiku iz mnogo kuteva te smo implementirali najbolje prakse.
- tehnologija koju koristite za pripremu dokumentacije (pisana dokumentacija, HTML, Wiki...)
Kao Atlassianovi partneri, okrenuti smo prema Confluenceu i svu svoju internu dokumentaciju radimo upravo koristeći Confluence. Ponekad korisnička dokumentacija ne može biti na Confluenceu jer klijenti uvjetuju gdje i kako će se ona dostaviti, ali i tada se sama priprema dokumentacije obavlja na Confluenceu te se samo konačna verzija prebacuje u PDF i šalje klijentu.
3. Je li vam korisnička dokumentacija pomogla u smanjenju količine rada u korisničkoj podršci tako da korisnici sami riješe probleme pomoću dokumentacije?
Iako ovdje nemamo baš konkretnih metrika/brojeva kojima bismo to potkrijepili, smatramo da jest. Odnosno, ovaj dio uvelike ovisi o komociji samih korisnika. Kao i svugdje, postoji dio korisnika koji će uzeti dokumentaciju i pomoću nje pokušati riješiti problem - dok postoji i onaj drugi, komotniji dio korisnika kojima je jednostavno puno lakše nazvati, napisati mail ili na bilo koji drugi način čekati da informacija sama pronađe njih.
Ondje gdje smo sigurni da nam dokumentacija uvelike olakšava je upravo na internom planu: sa samim onboardingom novih kolega, kod samostalnijeg rada, kod bržeg prijenosa znanja. Jednostavno vidimo velike benefite u tome i počeli smo dokumentirati sve procese unutar poduzeća, a ne samo ove vezane uz razvoj softvera.
Dokumentacija procesa
Kao što smo već ranije spomenuli, dokumentacija procesa sastoji se od različitih vrsta dokumenata za opisivanje samog postupka (procesa) razvoja softvera. Najčešće su to sljedeće komponente:
1. Planovi, procjene i rasporedi
Riječ je o dokumentima koji se u pravilu pripremaju prije početka glavnog dijela razvoja softvera, te se u praksi često mijenjaju tijekom samog rada na projektu. Je li netko spomenuo da se izmjene najčešće rade zbog kašnjenja?!
2. Izvještaji i metrika
Koriste se za pregled korištenja ljudskih resursa i vremena za rad na određenom projektu.
3. Standardi
Predstavljaju vrlo važan dio dokumentacije, jer se u njima definira način pisanja programskog koda, oblikovanje korisničkog sučelja i slično. Bez korištenja standarda u razvoju softvera (pogotovo kod velikih razvojnih timova) može se dobiti softver koji izgleda kao da su ga radile potpuno nepovezane grupe ljudi. Vjerujte autoru na riječ - prije mnogo godina je i sam sudjelovao u takvom razvoju projekta. Srećom, nakon određenog početnog gubitka vremena, ipak se prešlo na korištenje standarda.
4. Radna dokumentacija
Ne predstavlja glavni dio dokumentacije procesa, ali često može vrlo korisno opisivati pojedine ideje ili probleme koji se javljaju tijekom razvoja softvera, te način njihovog rješavanja.
Atos IT Solutions and Services
Kolika je važnost dokumentacije u sistemskoj integraciji i razvoju softvera otkriva nam Krešimir Pavić, CTO tvrtke Atos IT Solutions and Services d.o.o.
CTO tvrtke Atos IT Solutions and Services Krešimir Pavić.
U slučaju razvoja softvera, mi smo ti koji će morati sve napisati, što često izaziva noćne more i nelagodu kod developera.
Dokumentacija je sastavni dio obaveznih isporuka svakog projekta, čak i kada nije eksplicitno navedena u natječajnoj dokumentaciji. O veličini i tipu projekta ovisi kakva dokumentacija će se producirati. Atos djeluje unutar tri osnovna poslovanja (engl. line of business): poslovno/IT savjetovanje, sistemska integracija (što uključuje i razvoj softvera) i eksternalizacija (engl. outsourcing) što na visokoj razini definira minimum koji moramo isporučiti.
Za potrebe ovog članaka zadržat ćemo se na sistemskoj integraciji i razvoju softvera. U sistemskoj integraciji govorimo o instaliranju, podešavanju i prilagođavanju nekog velikog rješenja te integraciji s drugim sustavima. Proizvođač rješenja (npr. SAP, Oracle, Amdocs itd.) već posjeduje velik set dokumentacije (korisničke upute, administratorske upute, funkcionalne specifikacije, instalacijske upute itd.). Naš posao je prilagoditi tu dokumentaciju te prema potrebi kreirati novu. Najčešće moramo iznova napisati korisničke upute, a ostala dokumentacija ostaje kakva je bila. Poseban slučaj su državne firme koje često zahtijevaju da se sva dokumentacija isporuči na hrvatskom jeziku, što predstavlja dodatan trošak i otvara svu problematiku prijevoda na hrvatski. U slučaju razvoja softvera, mi smo ti koji će morati sve napisati, što često izaziva noćne more i nelagodu kod developera. Znači, nemamo posebno dedicirane osobe koje rade dokumentaciju. Današnje doba traži više uloga od jedne osobe. Razvoj softvera u našem je slučaju jednokratan projekt, tj. proizvod se razvija ekskluzivno za jednog klijenta, pa je onda i sva dokumentacija prilagođena tom klijentu. Ovdje klijent može očekivati funkcionalne i tehničke specifikacije, knjigu testova, korisničke upute, administratorske dokumente i instalacijske upute. Prije desetak godina se velik dio dokumentacije producirao samo zato što neka (razvojna) metodologija to nalaže.
Sada situacija nije takva i idemo na održivi minimum. Dokumentacija ne dolazi nužno u obliku MS Word dokumenta (odnosno PDF-a), ona može biti i tablica (najčešće MS Excel), a u novije vrijeme i u obliku MS PowerPoint dokumenta. MS PowerPoint može zamijeniti kako Word, tako i Visio ili neki drugi alat za crtanje arhitekture. Često imamo različite nazive i predloške za funkcionalne i tehničke specifikacije. Prema potrebama klijenta se stavlja veći ili manji naglasak na određene elemente tih dokumenata (npr. više na poslovne procese, a manje na integraciju i obrnuto). Oni su često najvažniji dokumenti tijekom projekta jer o njihovom sadržaju ovisi i sadržaj raznih uputa.
Najvažniji pozitivni učinci dokumentacije
Negativne učinke koji su posljedica nepotpune ili nepostojeće dokumentacije nećemo posebno raščlanjivati. Opišimo umjesto toga nešto detaljnije pozitivne posljedice.
1. Smanjenje u opterećenju korisničke podrške
U teoriji bi dobra korisnička dokumentacija trebala smanjiti opterećenje sustava korisničke podrške. Korisnik bi (bar u teoriji) u kvalitetnoj dokumentaciji trebao sam moći pronaći rješenje velikog broja problema, bez potrebe da njima opterećuje korisničku podršku. U praksi se ipak može naići na potpuno suprotne slučajeve, kada korisnici radije zatraže gotovo rješenje od podrške nego da se sami malo pomuče s dokumentacijom. Rješenje za takve korisnike je najčešće posebna naplata usluga podrške, ali to je već tema za neku drugu priliku.
2. Jednostavnija prodaja softvera
Ponekad postojanje kvalitetne korisničke dokumentacije može biti vrlo važan faktor kod odluke hoće li korisnik kupiti neki softver ili ne. Na primjer, ako se demo verzija aplikacije može isprobati prije same kupovine, a odgovarajuća prateća dokumentacija pojednostavljuje korištenje softvera i pregled njegovih mogućnosti, to može biti važnije za donošenje konačne odluke o kupovini od različitih propagandnih materijala i prezentacija.
3. Jednostavniji razvoj budućih verzija softvera
Dokumentacija namijenjena razvojnom timu predstavlja polaznu osnovu za razvoj novih verzija softvera. Tu se misli na planirane mogućnosti i ideje koje nisu uključene u prethodne verzije softvera. Također, kvalitetna dokumentacija je izvrsno polazište za uključivanje novih članova u razvojne timove.
Za ovaj put bi to bilo sve. Ako se do sada niste previše bavili ovom tematikom, nadamo se da ste dobili bar okvirni uvod u tematiku izrade dokumentacije za softverske projekte.
