Dokumenteerimine: kas, miks ja kuidas?

Analüütiku töös tuleb palju ette dokumenteerimist, küll on vaja nõudeid kirjutada, protsesse kirjeldada ja palju muud erinevat sorti infot dokumentidesse talletada. Kõik see ei ole lihtne tegevus. Dokumenteerimisel on palju erinevaid eesmärke ja selleks, et kirja pandut oleks võimalik efektiivselt kasutada, tuleb läbi mõelda, kellele dokument on, mis detailsusega infot on vaja talletada ning mis formaadis on kõige parem seda teha. Väga laialt võib öelda, et tehtud dokumentatsioon peab vastama järgnevatele tingimustele: see peab edasi andma vajalikku infot, see peab olema muudetav ning see peab olema valminud mõistliku ajaga (dokumenteerimine toetab tarkvara arendust, mitte ei ole eesmärk omaette).

Eelnevalt kirjeldatust tulenevalt proovin ma iga natukese aja tagant üle mõelda, et kas ma ikka kirjutan nii head dokumentatsiooni kui võimalik? Kas ma kirjutan liiga palju või liiga vähe? Kuidas ma saaks infot paremini edasi anda? Kuidas oma dokumentatsiooni paremini struktureerida ning mis erinevaid formaate kasutada saab?

Kahjuks on igas projektis dokumenteerimise vajadused erinevad ja seega ma ei saa siin kirjeldada, mis on kõige parem viis dokumenteerimiseks (ma ei ole senini veel ühest vastust leidnud). Küll aga saan ma ära kirjeldada need küsimused, mida saab enne dokumendi koostamist endalt küsida ning mis loodetavasti aitavad paremini aru saada, mida kirjutatavalt dokumendilt vaja on.

Kõigepealt tahan ma üldisema poole pealt üle käia küsimused, kas ja miks on vaja dokumenteerida. 

Kas on vaja dokumenteerida?

Üks agiilse metoodika põhimõtteid on, et “Töötav tarkvara on olulisem kui põhjalik dokumentatsioon” (“Working software over comprehensive documentation”). Sellest tulenevalt on üks ekstreemsemaid vaateid see, et dokumentatsiooni ei ole üldse vaja. Minu enda vaade on, et jah, dokumenteerida on kindlasti vaja, ning täpsemalt selgitan ma seda järgnevalt vastates küsimusele: “Miks?”. Üldiselt ma toetan agiilse põhimõtte järgi dokumenteerimist ehk siis nii palju kui vaja, siis kui vaja, aga kindlasti vaja.

On ka olemas vaade, et kood on dokumentatsioon. Jah, on olemas projekte, kus hästi kommenteeritud koodist piisab dokumenteerimiseks, aga neid on vähe. Ilma kommenteerimata kood on dokumentatsiooni osas täiesti kasutu. Põhjus on selles, et tahes tahtmata tehakse vigu ja kui koodi ei ole kommenteeritud, mis mingi kindla koodijupi eesmärk on, siis võib juhtuda, et hiljem vigast koodijuppi vaadates ei ole võimalik aru saada, mida tegelikult saavutada taheti. Lisaks sellele on kood väga piiratud moodus dokumenteerimiseks mitmel põhjusel. Visualiseerimine tekstina on keeruline ning tellijal ja ka osadel teistel projekti liikmetel reeglina ei ole moodust ega oskuseid selle lugemiseks. 

Miks dokumenteerida?

1. Inimesed unustavad – Ühe tarkvara eluiga võib varieeruda, aga parematel juhtudel on see siiski rohkem kui üks aasta. Potentsiaalselt isegi palju rohkem. Kogu tarkvara eluea jooksul tuleb ette küsimusi, näiteks “Kas see funktsionaalsus sai realiseeritud?”, “Kas see funktsionaalsus toimib nii, nagu sai algselt plaanitud?”, “´Mida see funktsionaalsus teeb?” ja veel palju muud. Mida rohkem aega möödub tarkvara valmimisest, seda väiksemaks läheb tõenäosus, et selle arendanud inimesed oskavad nendele küsimustele peast vastata. Kui seda infot ei ole dokumenteeritud, siis on see kadunud ja need küsimused jäävad vastuseta. Kui hästi läheb, siis selle tagajärjed ei ole suured, aga realistlikumalt on tulemuseks raha ja aja kulutamine kas siis topelt funktsionaalsuse realiseerimiseks või eelnevalt skoobist välja jäänud asjade arendamiseks, kuna pole kokkulepet mis näitaks, et see oli eelnevalt nii planeeritud.

2. Inimesed vahetuvad – Inimesed jäävad haigeks, käivad puhkamas ning vahetavad tööd. See on normaalne ja see ei tohi tähendada seda, et nende peas olev info on kas ajutiselt ligipääsmatu või siis halvemal juhul alatiseks läinud. Selleks, et teised inimesed saaksid üle võtta ja jätkata tööd, on vaja informatsiooni talletada ühel või teisel kujul. Ideaalne juht on muidugi see, kui info antakse edasi juhendamise teel, aga see ei pruugi alati olla võimalik ja juhendamist toetav dokumentatsioon on alati vajalik.

3. Ühtse arusaama kinnitamiseks – Kui tegemist on kliendi poolt tellitud spetsiaaltarkvaraga, siis kasutatakse dokumentatsiooni väga tihti tellitud funktsionaalsuse kinnitamiseks. Analüütik kirjeldab funktsionaalsuse dokumentatsioonis ning kui klient on selle üle lugenud ja läbi arutanud, siis see kinnitatakse. Peale kinnitamist on tegemist ametliku dokumendiga, mida saab tulevikus kasutada arveldamiseks ja pretensioonide lahendamiseks.

Kindlasti on ka rohkem põhjuseid, aga need kolm loetletut on käesoleval hetkel need, millega mina olen kõige rohkem kokku puutunud. 

Lisaks toon siia ka mõned näited, mis ei ole head põhjused dokumenteerimiseks.

1. Sest klient nõuab – Jah, on lepinguid, kus on kliendi poolt esitatud kindlad nõuded, mis dokumendid peavad olemas olema. Küll aga on kliendil olnud mingi põhjus need nõudmised lepingusse kirja panna. Analüütikuna tuleb aru saada, mis on see “Miks” nende dokumentide nõudmise taga ning mida klient tahab nende dokumentidega edasi teha.

2. Programmeerija tööks on vaja sisendit – Jah, programmeerijatele on abiks, kui nende töö sisendiks on dokumentatsioon, aga see sisend ei tohi olla ainult kirjalik. Programmeerijal on vaja tekitada endale arusaam sellest, mida on vaja arendada. Ainult dokumentatsioon ei ole selle arusaama tekitamiseks väga hea. Ennekõike tuleb programmeerijaga koos läbi arutada, mida on vaja teha ning mis peab olema tulemus, ja dokumentatsioon saab seda kõike toetada.

Mida kirjutada?

Kui nüüd on läbi mõeldud, et jah, dokumentatsiooni on vaja kirjutada, siis järgmiseks tuleb see keerulisem osa, ehk siis kuidas seda kirjutada? Nagu ma varem siin kirjutasin, ei ole ühtset head viisi, kuidas dokumenteerida. Igal projektil on omad vajadused, osad projektid vajavad integratsioonidokumentatsiooni, osade puhul piisab ainult kasutajalugudest (user story) ning muud projektid vajavad veel hoopis midagi teistsugust.

Selleks, et natukene paremat aimdust saada, mis dokumente ja kuidas teha, võiks mõelda järgnevatele asjadele:

Miks seda dokumenti vaja on?

Jälle see miks. Kõigepealt me vaatasime, miks üldiselt on dokumentatsiooni vaja, ja nüüd me peame iga dokumendi kohta eraldi aru saama, mis on selle dokumendi eesmärk, miks me seda kirjutame? Kui see dokument on valmis kirjutatud, siis kuidas seda kasutama hakatakse? Kui dokumendi lõppsaaja ütleb, et ega me selle dokumendiga midagi ei tee, paneme sahtlisse, siis selle dokumendi kirjutamisele ei peaks aega raiskama.

Kes hakkavad seda dokumentatsiooni lugema?

Selleks, et osata õiget infot kirja panna, peab aru saama, kes hakkavad seda tulevikus lugema. Näiteks on dokumente, mille eesmärk on edasi anda tehnilist informatsiooni. Sellisel juhul tuleb kirja panna detailid ja keskenduda väga spetsiifilisele info alamhulgale. Sellist informatsiooni loevad enamasti tehnilise taustaga inimesed (arhitekt, arendaja jne) ja kliendi äripoole esindaja ei peagi sellest dokumentatsioonist nii täpselt aru saama. 

Kui dokumentatsioon on aga mõeldud kõigile lugemiseks, siis ei ole hea mõte seda detailidega üle külvata, vaid pigem tuleks keskenduda üldpildile ja detailid jätta teiste dokumentide jaoks. Sellised dokumendid on enamasti mõeldud kas kliendi või tegija firma enda äripoolest teadvate inimeste jaoks ja need peavad sisaldama teistsugust infot ja teistsugusel kujul kui eelnevalt mainitud tehniline dokumentatsioon. 

Siin on kirjeldatud ainult kaks dokumendi lugejate äärmust, tegelikkuses võib olla rolle rohkem ning igaühe puhul tuleb mõelda selle üle, mis on lugejatele oluline.

Kas tegemist on ajutise või pikaajalise dokumentatsiooniga?

Kõik kirjutatud dokumendid ei pea elama pikka elu. Mõne dokumendi eluea pikkus võibki olla ainult nii kaua, kui võtab aega selles sisalduva info läbi töötamine. Näiteks minu kogemuses on prototüübist kasu olnud ainult senikaua, kuni prototüübil kujutatav on valmis tehtud. Edaspidi käib arutamine ja muudatuste tellimine siiski tarkvaras oleva pildi pealt ning prototüüp langeb unarusse (Kaja nentis peale lugemist, et tal on prototüüpidega teistsugused kogemused, aga üldmõttega oli nõus, et osa dokumentatsiooni on ajutine). Prototüüp on ainult üks näide, selliseid dokumente võib veel olla palju. Üldiselt ajutised dokumendid kipuvad olema need, millega antakse programmeerijatele edasi infot, kuidas asjad täpselt töötama peavad. Kui süsteem on realiseeritud, siis on väga keeruline neid dokumente sellise detailsusega ajakohasena hoida ning selleks pole ka vajadust.

Pikaajaline dokumentatsioon on see, mis peab tulevikus küsimuste tekkimisel aitama neile vastuseid leida. Kui detailne see dokumentatsioon on, on igaühe enda otsustada, aga väga oluline on see, et seda dokumentatsiooni hoitakse ajakohasena. Kui seda ajakohasena ei hoita, siis kaob sellel mõte ära. Jah, see tähendab seda, et iga väiksem muudatus tuleb sinna ära kirjeldada (kui see muudab dokumentatsiooni) ning sellest tulenevalt peab see olema võimalikult hästi struktureeritud, lihtsalt otsitav ja muudetav.

Kuidas kirjutada?

Nagu varem öeldud, dokumentatsiooni kirjutamine ei ole lihtne tegevus. Kõigepealt tuleb põhjalikult läbi mõelda, mida on vaja kirjutada, ja alles siis jõuab selle tegeliku küsimuseni, kuidas seda kirja panna. Paljud targad inimesed on oma töö jooksul välja mõelnud palju erinevaid formaate ja standardeid.

Kui vaadata üldiseid põhitõdesid, siis tuleb alati jälgida, et kirjutatud dokumentatsioon oleks struktureeritud. Tulevikus hakatakse sealt infot otsima ning struktuur on üks moodus, kuidas aidata otsitut kiiremini üles leida. Järgmine põhitõde on, et visualiseerida tuleb nii palju kui saab, sest keegi ei jaksa läbi lugeda mitut lehekülge teksti (irooniline asi, mida öelda blogiartiklis, kas pole). Protsessidiagrammid, olekumudelid, lihtsalt kastid ja ringid, mis iganes, mis aitab inimestel visuaalselt pilti paremini haarata. Ma ise näiteks olen enda kasutuslugudes (use case) protsessi kirjelduse teksti asendanud protsessi joonisega. Tekib natuke parem pilt alternatiivide ja üldse protsessi kohta.

Kasutada võib nii kasutuslugusid (use case) või kasutajalugusid (user story) või mingit muud struktureeritud teksti. Küll aga tuleb mõelda selle peale, et detaile tuleb kirja panna just nii palju, kui käesoleval hetkel vaja. Näiteks kasutajalugude mõte on see, et nad on lühikesed. Nende eesmärk ei ole kirjeldada kogu funktsionaalsust, vaid nad ongi mõeldud lühikokkuvõtteks, mida kasutatakse arutelu loomiseks. Kui kasutajalugu on meeskonnaga läbi arutatud, siis tekib sellest põhjalikum dokumentatsioon. Ehk siis arutelu käigus selguvad detailid ning ka see, mis sorti dokumentatsiooni vajavad arendajad enda töö sisendiks – mis info saab kirja panna kiiresti ja paari lausega ning mis läheb pikaajalisse dokumentatsiooni ja vajab rohkem tööd. 

Kui ette kirjutada väga põhjalik dokumentatsioon, siis tuleb ennast valmis panna selleks, et seda tuleb põhjalikult muutma hakata.

Rõhutan veelkord üle, et pikaajalist dokumentatsiooni tuleb hoida ajakohasena või muidu kaob selle mõte. Kui tehakse bugiparandusi või lisatakse uut funktsionaalsust, siis peaks kas projektijuht, tooteomanik või analüütik üle vaatama olemasoleva pikaajalise dokumentatsiooni ja seda täiendama. See peab olema muudatuse protsessi üks osa. Üks põhilisi põhjuseid, miks inimesed dokumentatsiooni vastu on, ongi see, et see on vananenud ja ei sisalda seda infot, mida vaja on. Sellise olukorra vältimiseks tuleb ennekõike teadvustada, et dokumentatsiooni peab ajakohasena hoidma ja selle peab oma tööprotsesside osaks tegema.

Ma väga põhjalikult ei kirjeldanud erinevad joonisetüüpe ega mudeleid, mida dokumenteerimiseks kasutada. Põhjus on selles, et erinevaid formaate on palju ja neil kõigil on oma head ja halvad küljed. Et natuke rohkem infot saada erinevate võimaluste kohta on mul endal kodus raamaturiiulil Business Analysis Techniques: 99 essential tools for success ja BABOK. Need kaks raamatut ei sisalda endas infot ainult dokumenteerimise kohta, vaid seal on ka palju muid töönippe analüütikute jaoks, aga siiski on nad ka väga head materjalid selleks, et tekitada arusaama, mis võimalused on olemas informatsiooni talletamiseks.
Siin kirjutatu on hoolimata oma pikkusest siiski üsna üldine ülevaade dokumenteerimise osas. Kui tekkis küsimusi, siis võib need postitada meie Facebooki lehele või saata meie e-mailidele kaja.trees@itbac.eu ja kristin.meriniit@itbac.eu.

Oleme alati rõõmsad küsimuste ja tagasiside üle!