{"id":664,"date":"2021-03-03T08:49:22","date_gmt":"2021-03-03T08:49:22","guid":{"rendered":"https:\/\/itbac.eu\/?p=274"},"modified":"2024-03-03T16:10:31","modified_gmt":"2024-03-03T16:10:31","slug":"dokumenteerimisest-kas-miks-ja-kuidas","status":"publish","type":"post","link":"https:\/\/dev.codenot.studio\/itbac\/dokumenteerimisest-kas-miks-ja-kuidas\/","title":{"rendered":"Dokumenteerimine: kas, miks ja kuidas?"},"content":{"rendered":"
\"\"
Dokumenteerimine on keeruline. People vector created by pch.vector – www.freepik.com<\/a><\/figcaption><\/figure>

Anal\u00fc\u00fctiku t\u00f6\u00f6s tuleb palju ette dokumenteerimist, k\u00fcll on vaja n\u00f5udeid kirjutada, protsesse kirjeldada ja palju muud erinevat sorti infot dokumentidesse talletada. K\u00f5ik see ei ole lihtne tegevus. Dokumenteerimisel on palju erinevaid eesm\u00e4rke ja selleks, et kirja pandut oleks v\u00f5imalik efektiivselt kasutada, tuleb l\u00e4bi m\u00f5elda, kellele dokument on, mis detailsusega infot on vaja talletada ning mis formaadis on k\u00f5ige parem seda teha. V\u00e4ga laialt v\u00f5ib \u00f6elda, et tehtud dokumentatsioon peab vastama j\u00e4rgnevatele tingimustele: see peab edasi andma vajalikku infot, see peab olema muudetav ning see peab olema valminud m\u00f5istliku ajaga (dokumenteerimine toetab tarkvara arendust, mitte ei ole eesm\u00e4rk omaette).<\/p>

Eelnevalt kirjeldatust tulenevalt proovin ma iga natukese aja tagant \u00fcle m\u00f5elda, et kas ma ikka kirjutan nii head dokumentatsiooni kui v\u00f5imalik? Kas ma kirjutan liiga palju v\u00f5i liiga v\u00e4he? Kuidas ma saaks infot paremini edasi anda? Kuidas oma dokumentatsiooni paremini struktureerida ning mis erinevaid formaate kasutada saab?<\/p>

Kahjuks on igas projektis dokumenteerimise vajadused erinevad ja seega ma ei saa siin kirjeldada, mis on k\u00f5ige parem viis dokumenteerimiseks (ma ei ole senini veel \u00fchest vastust leidnud). K\u00fcll aga saan ma \u00e4ra kirjeldada need k\u00fcsimused, mida saab enne dokumendi koostamist endalt k\u00fcsida ning mis loodetavasti aitavad paremini aru saada, mida kirjutatavalt dokumendilt vaja on.<\/p>

K\u00f5igepealt tahan ma \u00fcldisema poole pealt \u00fcle k\u00e4ia k\u00fcsimused, kas ja miks on vaja dokumenteerida. <\/p>

Kas on vaja dokumenteerida?<\/h3>

\u00dcks agiilse metoodika p\u00f5him\u00f5tteid on, et \u201cT\u00f6\u00f6tav tarkvara on olulisem kui p\u00f5hjalik dokumentatsioon\u201d (\u201cWorking software over comprehensive documentation\u201d). Sellest tulenevalt on \u00fcks ekstreemsemaid vaateid see, et dokumentatsiooni ei ole \u00fcldse vaja. Minu enda vaade on, et jah, dokumenteerida on kindlasti vaja, ning t\u00e4psemalt selgitan ma seda j\u00e4rgnevalt vastates k\u00fcsimusele: \u201cMiks?\u201d. \u00dcldiselt ma toetan agiilse p\u00f5him\u00f5tte j\u00e4rgi dokumenteerimist ehk siis nii palju kui vaja, siis kui vaja, aga kindlasti vaja.<\/p>

On ka olemas vaade, et kood on dokumentatsioon. Jah, on olemas projekte, kus h\u00e4sti kommenteeritud koodist piisab dokumenteerimiseks, aga neid on v\u00e4he. Ilma kommenteerimata kood on dokumentatsiooni osas t\u00e4iesti kasutu. P\u00f5hjus on selles, et tahes tahtmata tehakse vigu ja kui koodi ei ole kommenteeritud, mis mingi kindla koodijupi eesm\u00e4rk on, siis v\u00f5ib juhtuda, et hiljem vigast koodijuppi vaadates ei ole v\u00f5imalik aru saada, mida tegelikult saavutada taheti. Lisaks sellele on kood v\u00e4ga piiratud moodus dokumenteerimiseks mitmel p\u00f5hjusel. Visualiseerimine tekstina on keeruline ning tellijal ja ka osadel teistel projekti liikmetel reeglina ei ole moodust ega oskuseid selle lugemiseks. <\/p>

Miks dokumenteerida?<\/h3>

1. Inimesed unustavad<\/strong> – \u00dche tarkvara eluiga v\u00f5ib varieeruda, aga parematel juhtudel on see siiski rohkem kui \u00fcks aasta. Potentsiaalselt isegi palju rohkem. Kogu tarkvara eluea jooksul tuleb ette k\u00fcsimusi, n\u00e4iteks \u201cKas see funktsionaalsus sai realiseeritud?\u201d, \u201cKas see funktsionaalsus toimib nii, nagu sai algselt plaanitud?\u201d, \u201c\u00b4Mida see funktsionaalsus teeb?\u201d ja veel palju muud. Mida rohkem aega m\u00f6\u00f6dub tarkvara valmimisest, seda v\u00e4iksemaks l\u00e4heb t\u00f5en\u00e4osus, et selle arendanud inimesed oskavad nendele k\u00fcsimustele peast vastata. Kui seda infot ei ole dokumenteeritud, siis on see kadunud ja need k\u00fcsimused j\u00e4\u00e4vad vastuseta. Kui h\u00e4sti l\u00e4heb, siis selle tagaj\u00e4rjed ei ole suured, aga realistlikumalt on tulemuseks raha ja aja kulutamine kas siis topelt funktsionaalsuse realiseerimiseks v\u00f5i eelnevalt skoobist v\u00e4lja j\u00e4\u00e4nud asjade arendamiseks, kuna pole kokkulepet mis n\u00e4itaks, et see oli eelnevalt nii planeeritud.<\/p>

2. Inimesed vahetuvad<\/strong> – Inimesed j\u00e4\u00e4vad haigeks, k\u00e4ivad puhkamas ning vahetavad t\u00f6\u00f6d. See on normaalne ja see ei tohi t\u00e4hendada seda, et nende peas olev info on kas ajutiselt ligip\u00e4\u00e4smatu v\u00f5i siis halvemal juhul alatiseks l\u00e4inud. Selleks, et teised inimesed saaksid \u00fcle v\u00f5tta ja j\u00e4tkata t\u00f6\u00f6d, on vaja informatsiooni talletada \u00fchel v\u00f5i teisel kujul. Ideaalne juht on muidugi see, kui info antakse edasi juhendamise teel, aga see ei pruugi alati olla v\u00f5imalik ja juhendamist toetav dokumentatsioon on alati vajalik.<\/p>

3. \u00dchtse arusaama kinnitamiseks<\/strong> – Kui tegemist on kliendi poolt tellitud spetsiaaltarkvaraga, siis kasutatakse dokumentatsiooni v\u00e4ga tihti tellitud funktsionaalsuse kinnitamiseks. Anal\u00fc\u00fctik kirjeldab funktsionaalsuse dokumentatsioonis ning kui klient on selle \u00fcle lugenud ja l\u00e4bi arutanud, siis see kinnitatakse. Peale kinnitamist on tegemist ametliku dokumendiga, mida saab tulevikus kasutada arveldamiseks ja pretensioonide lahendamiseks.<\/p>

Kindlasti on ka rohkem p\u00f5hjuseid, aga need kolm loetletut on k\u00e4esoleval hetkel need, millega mina olen k\u00f5ige rohkem kokku puutunud. <\/p>

Lisaks toon siia ka m\u00f5ned n\u00e4ited, mis ei ole head p\u00f5hjused dokumenteerimiseks.<\/p>

1. Sest klient n\u00f5uab<\/strong> – Jah, on lepinguid, kus on kliendi poolt esitatud kindlad n\u00f5uded, mis dokumendid peavad olemas olema. K\u00fcll aga on kliendil olnud mingi p\u00f5hjus need n\u00f5udmised lepingusse kirja panna. Anal\u00fc\u00fctikuna tuleb aru saada, mis on see \u201cMiks\u201d nende dokumentide n\u00f5udmise taga ning mida klient tahab nende dokumentidega edasi teha.<\/p>

2. Programmeerija t\u00f6\u00f6ks on vaja sisendit<\/strong> – Jah, programmeerijatele on abiks, kui nende t\u00f6\u00f6 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\u00e4ga hea. Ennek\u00f5ike tuleb programmeerijaga koos l\u00e4bi arutada, mida on vaja teha ning mis peab olema tulemus, ja dokumentatsioon saab seda k\u00f5ike toetada.<\/p>

Mida kirjutada?<\/h3>

Kui n\u00fc\u00fcd on l\u00e4bi m\u00f5eldud, et jah, dokumentatsiooni on vaja kirjutada, siis j\u00e4rgmiseks tuleb see keerulisem osa, ehk siis kuidas seda kirjutada? Nagu ma varem siin kirjutasin, ei ole \u00fchtset 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.<\/p>

Selleks, et natukene paremat aimdust saada, mis dokumente ja kuidas teha, v\u00f5iks m\u00f5elda j\u00e4rgnevatele asjadele:<\/p>

Miks seda dokumenti vaja on?<\/strong><\/p>

J\u00e4lle see miks. K\u00f5igepealt me vaatasime, miks \u00fcldiselt on dokumentatsiooni vaja, ja n\u00fc\u00fcd me peame iga dokumendi kohta eraldi aru saama, mis on selle dokumendi eesm\u00e4rk, miks me seda kirjutame? Kui see dokument on valmis kirjutatud, siis kuidas seda kasutama hakatakse? Kui dokumendi l\u00f5ppsaaja \u00fctleb, et ega me selle dokumendiga midagi ei tee, paneme sahtlisse, siis selle dokumendi kirjutamisele ei peaks aega raiskama.<\/p>

Kes hakkavad seda dokumentatsiooni lugema?<\/strong><\/p>

Selleks, et osata \u00f5iget infot kirja panna, peab aru saama, kes hakkavad seda tulevikus lugema. N\u00e4iteks on dokumente, mille eesm\u00e4rk on edasi anda tehnilist informatsiooni. Sellisel juhul tuleb kirja panna detailid ja keskenduda v\u00e4ga spetsiifilisele info alamhulgale. Sellist informatsiooni loevad enamasti tehnilise taustaga inimesed (arhitekt, arendaja jne) ja kliendi \u00e4ripoole esindaja ei peagi sellest dokumentatsioonist nii t\u00e4pselt aru saama. <\/p>

Kui dokumentatsioon on aga m\u00f5eldud k\u00f5igile lugemiseks, siis ei ole hea m\u00f5te seda detailidega \u00fcle k\u00fclvata, vaid pigem tuleks keskenduda \u00fcldpildile ja detailid j\u00e4tta teiste dokumentide jaoks. Sellised dokumendid on enamasti m\u00f5eldud kas kliendi v\u00f5i tegija firma enda \u00e4ripoolest teadvate inimeste jaoks ja need peavad sisaldama teistsugust infot ja teistsugusel kujul kui eelnevalt mainitud tehniline dokumentatsioon. <\/p>

Siin on kirjeldatud ainult kaks dokumendi lugejate \u00e4\u00e4rmust, tegelikkuses v\u00f5ib olla rolle rohkem ning iga\u00fche puhul tuleb m\u00f5elda selle \u00fcle, mis on lugejatele oluline.<\/p>

Kas tegemist on ajutise v\u00f5i pikaajalise dokumentatsiooniga?<\/strong><\/p>

K\u00f5ik kirjutatud dokumendid ei pea elama pikka elu. M\u00f5ne dokumendi eluea pikkus v\u00f5ibki olla ainult nii kaua, kui v\u00f5tab aega selles sisalduva info l\u00e4bi t\u00f6\u00f6tamine. N\u00e4iteks minu kogemuses on protot\u00fc\u00fcbist kasu olnud ainult senikaua, kuni protot\u00fc\u00fcbil kujutatav on valmis tehtud. Edaspidi k\u00e4ib arutamine ja muudatuste tellimine siiski tarkvaras oleva pildi pealt ning protot\u00fc\u00fcp langeb unarusse (Kaja nentis peale lugemist, et tal on protot\u00fc\u00fcpidega teistsugused kogemused, aga \u00fcldm\u00f5ttega oli n\u00f5us, et osa dokumentatsiooni on ajutine). Protot\u00fc\u00fcp on ainult \u00fcks n\u00e4ide, selliseid dokumente v\u00f5ib veel olla palju. \u00dcldiselt ajutised dokumendid kipuvad olema need, millega antakse programmeerijatele edasi infot, kuidas asjad t\u00e4pselt t\u00f6\u00f6tama peavad. Kui s\u00fcsteem on realiseeritud, siis on v\u00e4ga keeruline neid dokumente sellise detailsusega ajakohasena hoida ning selleks pole ka vajadust.<\/p>

Pikaajaline dokumentatsioon on see, mis peab tulevikus k\u00fcsimuste tekkimisel aitama neile vastuseid leida. Kui detailne see dokumentatsioon on, on iga\u00fche enda otsustada, aga v\u00e4ga oluline on see, et seda dokumentatsiooni hoitakse ajakohasena. Kui seda ajakohasena ei hoita, siis kaob sellel m\u00f5te \u00e4ra. Jah, see t\u00e4hendab seda, et iga v\u00e4iksem muudatus tuleb sinna \u00e4ra kirjeldada (kui see muudab dokumentatsiooni) ning sellest tulenevalt peab see olema v\u00f5imalikult h\u00e4sti struktureeritud, lihtsalt otsitav ja muudetav.<\/p>

Kuidas kirjutada?<\/h3>

Nagu varem \u00f6eldud, dokumentatsiooni kirjutamine ei ole lihtne tegevus. K\u00f5igepealt tuleb p\u00f5hjalikult l\u00e4bi m\u00f5elda, mida on vaja kirjutada, ja alles siis j\u00f5uab selle tegeliku k\u00fcsimuseni, kuidas seda kirja panna. Paljud targad inimesed on oma t\u00f6\u00f6 jooksul v\u00e4lja m\u00f5elnud palju erinevaid formaate ja standardeid.<\/p>

Kui vaadata \u00fcldiseid p\u00f5hit\u00f5desid, siis tuleb alati j\u00e4lgida, et kirjutatud dokumentatsioon oleks struktureeritud. Tulevikus hakatakse sealt infot otsima ning struktuur on \u00fcks moodus, kuidas aidata otsitut kiiremini \u00fcles leida. J\u00e4rgmine p\u00f5hit\u00f5de on, et visualiseerida tuleb nii palju kui saab, sest keegi ei jaksa l\u00e4bi lugeda mitut lehek\u00fclge teksti (irooniline asi, mida \u00f6elda blogiartiklis, kas pole). Protsessidiagrammid, olekumudelid, lihtsalt kastid ja ringid, mis iganes, mis aitab inimestel visuaalselt pilti paremini haarata. Ma ise n\u00e4iteks olen enda kasutuslugudes (use case) protsessi kirjelduse teksti asendanud protsessi joonisega. Tekib natuke parem pilt alternatiivide ja \u00fcldse protsessi kohta.<\/p>

Kasutada v\u00f5ib nii kasutuslugusid (use case) v\u00f5i kasutajalugusid (user story) v\u00f5i mingit muud struktureeritud teksti. K\u00fcll aga tuleb m\u00f5elda selle peale, et detaile tuleb kirja panna just nii palju, kui k\u00e4esoleval hetkel vaja. N\u00e4iteks kasutajalugude m\u00f5te on see, et nad on l\u00fchikesed. Nende eesm\u00e4rk ei ole kirjeldada kogu funktsionaalsust, vaid nad ongi m\u00f5eldud l\u00fchikokkuv\u00f5tteks, mida kasutatakse arutelu loomiseks. Kui kasutajalugu on meeskonnaga l\u00e4bi arutatud, siis tekib sellest p\u00f5hjalikum dokumentatsioon. Ehk siis arutelu k\u00e4igus selguvad detailid ning ka see, mis sorti dokumentatsiooni vajavad arendajad enda t\u00f6\u00f6 sisendiks – mis info saab kirja panna kiiresti ja paari lausega ning mis l\u00e4heb pikaajalisse dokumentatsiooni ja vajab rohkem t\u00f6\u00f6d. <\/p>

Kui ette kirjutada v\u00e4ga p\u00f5hjalik dokumentatsioon, siis tuleb ennast valmis panna selleks, et seda tuleb p\u00f5hjalikult muutma hakata.<\/p>

R\u00f5hutan veelkord \u00fcle, et pikaajalist dokumentatsiooni tuleb hoida ajakohasena v\u00f5i muidu kaob selle m\u00f5te. Kui tehakse bugiparandusi v\u00f5i lisatakse uut funktsionaalsust, siis peaks kas projektijuht, tooteomanik v\u00f5i anal\u00fc\u00fctik \u00fcle vaatama olemasoleva pikaajalise dokumentatsiooni ja seda t\u00e4iendama. See peab olema muudatuse protsessi \u00fcks osa. \u00dcks p\u00f5hilisi p\u00f5hjuseid, miks inimesed dokumentatsiooni vastu on, ongi see, et see on vananenud ja ei sisalda seda infot, mida vaja on. Sellise olukorra v\u00e4ltimiseks tuleb ennek\u00f5ike teadvustada, et dokumentatsiooni peab ajakohasena hoidma ja selle peab oma t\u00f6\u00f6protsesside osaks tegema.<\/p>

Ma v\u00e4ga p\u00f5hjalikult ei kirjeldanud erinevad jooniset\u00fc\u00fcpe ega mudeleid, mida dokumenteerimiseks kasutada. P\u00f5hjus on selles, et erinevaid formaate on palju ja neil k\u00f5igil on oma head ja halvad k\u00fcljed. Et natuke rohkem infot saada erinevate v\u00f5imaluste kohta on mul endal kodus raamaturiiulil Business Analysis Techniques: 99 essential tools for success<\/a> ja BABOK<\/a>. Need kaks raamatut ei sisalda endas infot ainult dokumenteerimise kohta, vaid seal on ka palju muid t\u00f6\u00f6nippe anal\u00fc\u00fctikute jaoks, aga siiski on nad ka v\u00e4ga head materjalid selleks, et tekitada arusaama, mis v\u00f5imalused on olemas informatsiooni talletamiseks.
Siin kirjutatu on hoolimata oma pikkusest siiski \u00fcsna \u00fcldine \u00fclevaade dokumenteerimise osas. Kui tekkis k\u00fcsimusi, siis v\u00f5ib need postitada meie Facebooki lehele v\u00f5i saata meie e-mailidele kaja.trees@itbac.eu ja kristin.meriniit@itbac.eu. <\/p>

Oleme alati r\u00f5\u00f5msad k\u00fcsimuste ja tagasiside \u00fcle!<\/p>