Sellepärast ma kirjutasingi raamatu Optimaalne dokumentatsioon: kasulik, ajakohane ja mugav

Karjääri alguses olin samamoodi frustreerunud. Nägin tihti meeskondasid, kes jätsid dokumentatsiooni tegemata või, mis veel hullem, lõid hunnikute viisi aegunud faile, mida ei saanud usaldada. Äri- ja süsteemianalüütikuna ei saanud ma mööda vaadata sellest, kui palju aega ja raha raisati, kuna õige info polnud õigel ajal kättesaadav. Samas kogesin neid raskusi omal nahal — dokumentatsiooni asjakohase ja ajakohasena hoidmine ei ole intuitiivne tegevus ning keegi ei osanud mulle ka õpetada, kuidas seda teha.

Aastate jooksul õppisin läbi katse-eksituse meetodi dokumenteerimise parimad praktikas, mis aitasid mind järjel püsida. Ma leidsin viisid, kuidas kirjutada kasulikku ja lihtsasti hallatavat dokumentatsiooni, ja mis tõesti toetab meeskonda – ja seda lähenemist ma siin raamatus jagangi.

Siin on mõned mõtted sellest raamatust.

1. Dokumentatsiooni kohta on palju müüte ja halba argumentatsiooni, mis võtab ära motivatsiooni sellega tegeleda

Artikkel “Lükkame ümber 6 müüti dokumenteerimisest” on täielikult raamatusse kaasatud, aga ma räägin seal ka lihtsalt halbadest põhjendustest:

Χ „Peab”, „ülemus käskis”.
Χ Nii on alati tehtud.
Χ See on ju analüütiku väljund.
Χ Lepinguliste kohustuste täitmiseks.
Neid argumente kuulen ma tihti. Kui sina oma töös selliseid põhjendusi kuuled, et lihtsalt
peab või keegi käskis, siis pole imestada, kui ei tunne erilist motivatsiooni dokumentatsiooni
kirjutamiseks. Selliste argumentide puhul tasub alati küsida „miks?” ja see enda
jaoks päriselt lahti mõtestada, muidu on tõesti õigustatud jätta dokumentatsioon tegemata.

1. peatükk: Miks ei taheta dokumenteerida?

Tõeliselt kasuliku dokumentatsiooni kirjutamiseks on oluline aru saada, miks me seda kirjutame, kellele ja milline dokumentatsioon on päriselt abiks.

2. Dokumentatsioon peaks abistama sind ennast

Tihtipeale on nii, et käin kliendiga koosolekul, kus ta mulle oma ideid ja vajadusi selgitab
ja kõik küsimused vastab. Mulle tundub, et kõik on arusaadav… Aga siis hakkan seda
loogilist tervikut kirja panema ja leian, et on veel detaile või lünkasid, mida oleks vaja
täita. Dokumentatsiooni süstemaatiline olemus aitab reaalselt kogu terviku läbi mõelda
ja puudused esile tuua.

2. peatükk: Dokumenteerimine on kasulik sulle endale

Hea dokumentatsioon ei ole ainult auditeerijatele üleandmiseks – see on tööriist mõtlemiseks. See aitab sul varakult üles leida puuduvat infot, vähendab korduvaid seletamisi ja teeb põhjendatud otsuste tegemise kergemaks.

3. Integreeri ajakohastamine oma töövoogu

Üks levinumaid dokumenteerimise vastuargumente on, et “Dokumentatsioon on nagunii aegunud“

Aga see ei pea nii olema ja loomulikult on rohkem kasu ajakohasest dokumentatsioonist.
Ja dokumentatsiooni ajakohasena hoida on ka täiesti võimalik! Selleks tuleb dokumentatsiooni
vastavalt vajadusele uuendada. Loomulikult vajab see kindlat vastutajat, kellel
on järjekindlust ja oskust seda teha.
Seda, kuidas mina olen selle enda jaoks lahendanud, räägin „Ajakohane“ osas. Seal selgitan,
kuidas dokumentatsiooni uuendamise saab integreerida dokumenteerimise loomuliku
osana oma tööprotsessi.

1. peatükk: Miks ei taheta dokumenteerida?

Ma jagan praktilisi viise dokumentatsiooni ajakohasena hoida ka oma artiklis “Alati ajakohane dokumentatsioon on võimalik” – ja raamatus kirjutan selle dokumenteerimise parimate praktikate raamistiku detailselt lahti.

4. Sa ei pea dokumenteerima kõike

Tegusatel meeskondadel ei ole luksust kirjutada romaane. Seepärast keskenduvad minu dokumenteerimise parimad tavad sellele, et dokumentatsioon oleks projekti vajadustele piisava mahuga — nii palju, kui on vaja selguse andmiseks, kuid mitte nii palju, et muutuks raskesti hallatavaks.

Nende mudelite vahel peab targalt valikuid tegema. Näiteks ka maakaardist on võimalik
luua palju erinevaid vaateid – liiklusskeem, elektripaigaldiste info, katastripiirid,
maavarade kaart jpm. Kõiki neid ei ole vaja luua – kui ei ole tegu just keskse geoinfo
teenusega – vaid piisab baaskaardist ja sellele loodud vaatest, mis just meie sihtgrupile
vajaliku info nähtavaks teeb. /…/

Teisalt, jätkates kaardi näitega, saame me valida ka õige detailsustaseme – millisel suurendustasemel
kaarti meil on vajalik mingil juhul vaadata? /…/

IT-süsteemide dokumenteerimisel luuakse tihtipeale dokumentatsiooni erineva detailsusega
vaadetena, kus üldisema tasandi vaatel on komponentideks detailsema taseme
vaated ja nende seosed. Nii tekib hierarhia, kus detailsemal tasemel on palju rohkem
vaateid/dokumente kui üldisematel – ja see tekitab ka mõtte, et ehk ei kirjutaks lahendust
dokumendi tasandil nii detailselt läbi, et halduskoormust vähendada.

6. peatükk: Piisav dokumentatsioon

Vajalike dokumentatsiooni liikide ja üldistuse tasemete läbimõtlemine aitab sul teha dokumentatsiooni osas tarkasid valikuid. See aitab sul hallata oma töökoormust – teha ainult seda, mis on päriselt vajalik. Raamatus ma selgitan, kuidas tuvastada õiged mudelid ja vajalik detailsustase.

Kas oled valmis muutma enda dokumentatsiooni kasulikuks ja kergesti hallatavaks?

Kui oled ärianalüütik, süsteemianalüütik, projektijuht, tootejuht, tooteomanik — või lihtsalt osa hõivatud IT-tiimist —, siis võid lõpetada dokumentatsiooni käsitlemise tüütu kohustusena ja hakata seda kasutama tootlikkuse tööriistana.

Selles raamatus käime samm-sammult läbi kuidas mõista frustratsiooni põhjuseid ja dokumentatsiooni väärtust kuni praktiliste põhimõteteni, kuidas muuta dokumentatsioon tõeliselt kasulikuks, arusaadavaks ja mugavaks. Kuigi mainin vastavalt vajadusele ka standardeid ja raamistikke, keskendub see raamat dokumenteerimise parimatele tavadele, mida saab rakendada igal pool. Teooriale lisaks on enamiku peatükkide juures ka harjutused, mis aitavad sul teemat sügavamalt mõista ja seda just enda dokumentatsiooni ja protsesside puhul rakendada.

Loe täpsemalt raamatust Optimaalne dokumentatsioon: kasulik, ajakohane ja mugav, mis on saadaval nii e-raamatuna kui ka pehmete kaantega väljaandena. Kui soovid teemat kogu oma meeskonnaga samm-sammult läbi käia, on sellel teemal saadaval ka koolitus-töötuba.

Minu enda suurimaks nõrkuseks on (minu enda hinnangul) küsimuste esitamine. Tihtipeale ei oska ma küsida ka siis, kui selge on ainult see, et ma ei saa millestki aru. Ometi peab kuskilt alustama…

Leidsin autistlike inimeste maailmast raamatu „5 küsimust“. See raamat ütleb, et autistlikel lastel on kergem, kui alati vastata viiele küsimusele: “miks?”, “kes?”, “kus?”, “millal?” ja “kuidas?”. Olen hakanud samu küsimusi kasutama, et IT-projektides kõik vajalik teada saada.

Miks?

Miks seda projekti üldse läbi viiakse? Mis eesmärke tahetakse sellega saavutada? Milliseid mõõdikuid soovitakse sellega parandada? Miks on just need mõõdikud nii olulised?

Kui miks ei ole selge, ei ole mõtet järgmiste küsimuste juurde minnagi. Simon Sinek on kirjutanud raamatu „Esmalt küsi miks“. Ma ei ole seda lugenud, kuid ma olen selle raamatu pealkirjaga nõus selletagi. See küsimus on kõige olulisem, kõige lihtsam küsida – ja samas kõige alakasutatum. “Miks?”’ist lähtudes saab seada prioriteete ja suunata sobivamale funktsionaalsusele. Sellele küsimusele mittevastav IT-süsteem on kõigi osapoolte aja ja raha raiskamine.

“Miks?” seab kogu projektile eesmärgi ning seab selle ümbritseva maailma konteksti. Sellest lähtuvalt on kõigil osapooltel selgem alus otsuste tegemisel. Oluline on ka seotud vastupidine küsimus “Miks mitte?”. Näiteks ei ole vaja realiseerida olemasolevat funktsionaalsust või parasjagu vähem tähtsat nõuet. See seab piirid projekti skoobile ja aitab tagada õigeaegset valmimist.

Vastus „Miks?“ile ei jõua tihti dokumentatsiooni. Mina ei ole veel leidnud ka ühtegi head tehnikat, millega seda sinna alati lisada. “Miks?” peaks olema eelkõige visiooni, lähteülesande või projekti lepingu osa. Kuna see on tellija poolt ette antud, siis ei ole sellel standardset struktuuri. Ärianalüüsi käigus analüüsitakse erinevate tehnikate abil (SWOT, MOST, PESTLE, äriplaan jne) taustsüsteemi, kuid põhjus on ka neis vaid väike osa. “5 miksi” tehnika aitab sügavamaid põhjuseid välja uurida, kuid seda tehnikat kasutatakse minu kogemusel harva, ja ka siis ainult alguses.

Kui “Miks”’i ei ole välja selgitatud, siis:

• Töö on mehhaaniline ja veaohtlik kõigil rollidel – arendajatel, testijatel, juurutajatel;
• Programmi parandajad ja hiljem edasi arendajad võivad minna “Miks”’iga vastuollu;
• Keegi ei tea, kas kirjeldatud funktsionaalsus on tegelikult vajalik või on analüütik selle välja pakkunud oma arvamuse põhjal.

Agiilne tarkvaraarendus lahendab probleemi sellega, et toob kliendi ja arendaja sama laua taha. Samas ka sellisel juhul jääb „Miks?“ ainult mällu. Juba paari iteratsiooni järel ei mäletata vahel, miks lahendus on loodud just selliselt. Sellega võib kaotada kliendile vajalikku, mida on vaja siis taastada.
„Miks?“ tuleks küsida ka kõigi järgnevate küsimuste alamküsimusena:

• „Miks tema projektist huvitatud on?“
• „Miks just nii?“
• „Miks just sellisel ajal, sellise regulaarsusega?“
• „Miks just seal?”

Kes?

Kes on selle projekti tellija? Kes on selle süsteemi kasutajad? Kes on sellest süsteemist mingil muul moel huvitatud?

“Kes?” on tihti IT-projekti alguspunkt, sest nagu öeldakse – kes maksab, see tellib ka muusika. Tellija „miks“ on projekti jaoks kõige tähtsam, just tellija eesmärke peab projekt esimeses järjekorras täitma. Küll aga peab analüütik vaatama kogu lahendust kõigi huvitatute vaatenurgast. Selle väljaselgitamiseks tehakse osapoolte analüüs, milleks saab kasutada erinevaid tehnikaid.

„Kes?“ ütleb analüütikule, kellega tal on vaja projekti raames rääkida või kelle huvide kohta tuleb infot muudest kanalitest otsida.

Sellele küsimusele saab anda ka levinumad vastused. Esiteks tellija ja erinevad rollid, kes loodavat süsteemi hakkavad kasutama. Analüütik veedabki suurema osa ajast nendega koos või nende vaatepunktist lähtuvalt. Kergesti võivad kahe silma vahele jääda aga:

• riiklikud nõudmised (kui tellija seda ise välja ei oska tuua);
• konkurentide huvi (millele ilmselt vastupidiselt tahame toimida);
• raamatupidamise/juhtkonna jaoks vajalike tulemuste kättesaadavus;
• ja süsteemi haldajate vajadused.

Selguvad vajadused on tavaliselt vastuolulised, kuid nende vahel tuleb leida just tellijale sobiv lahendus.

Kus?

Kus tulevane kasutaja praegu vajalikke toiminguid teeb? Milline on kasutajate ja tellija visioon, kus kasutaja saab tulevikus vajalikud toimingud teha? Kus on toodud süsteemi huvitatud isikutele vajalik info?

„Kus?“ räägib esiteks loodava lahenduse arhitektuurist. Näiteks, millised vaated on vajalikud, kuidas andmeid säilitatakse, millised süsteemid on kaasatud – või ei ole.

Teiseks räägib “kus?” tulevaste kasutajate kasutatavatest seadmetest. Võibolla on kasutajaks tehnik, kes objektil viibides kasutab väikese ekraaniga mobiiltelefoni? Võibolla varem seda ei olnud ning projekti raames tuleb ka sobiv seade leida? Võibolla on kõigil tulevastel kasutajatel kohustuslik teatud operatsioonisüsteemi kasutamine? Võibolla on mõistlik, et osaliselt jätkatakse olemasolevate lahenduste kasutamist? Seda võidakse teha näiteks ajapuudusel, üleminekuna või ka osa arenduse asemel.

“Kus?”-küsimuse erinevad tahud kirjeldatakse (mittefunktsionaalsetes) nõuetes, arhitektuuri kirjeldustes ja paigaldusvaadetes. Samuti mainitakse seda protsessidiagrammidel, kasutuslugudes ja kasutusjuhtudes.

Millal?

Millal protsess käivituma peab? Mis on erinevate protsesside järjestus, tihedus? Millal kasutaja peab mingit infot nägema? Millal peavad mingi protsessi tulemused valmis olema?

“Millal?” aitab otsustada, kas mingi protsess automatiseerida või teha käsitsi kättesaadavaks. Tihedamini kasutatavad protsessid ja info võib olla vajalik tuua süsteemis esile. Ajakriitilisi protsesse võib vaja olla optimeerida.

„Millal?“ annab eelkõige infot selle kohta, milline saab loodav lahendus olla. See info kirjeldatakse nõuetes, protsessides ja kasutuslugudes.

Kuidas?

Kuidas süsteemi tulevased kasutajad neid tegevusi praegu teevad? Milline on tellija või kasutajate visioon, kuidas nad saaksid seda tulevikus teha? Kuidas oleks kõige mugavam/efektiivsem/veatum viis jõuda tulemuseni?
Kuidas saaks tellijale pakkuda parima lahenduse etteantud aja- ja raha raamides?

“Kuidas?” küsimusega tegeletakse suurem osa IT-projekti koosolekuid ja analüütiku üksinda veedetud tunde. See aitab aru saada kõikidest detailidest, mis eelmiste küllaltki üldiste küsimuste juures välja ei tule. Selle abil analüütik mõistab, kuidas toimivad protsessid uues süsteemis või selle ümber.

“Kuidas?” juures on oht unustada ära „Miks?“. Näiteks luuakse süsteem täpselt olemasoleva paberil või Excelile toetuva protsessi põhjal. Sellises süsteemis puudub lisandväärtus protsessi optimeerimise näol.

„Kuidas“ kirjeldatakse enamasti kas protsessidiagrammide, kasutusjuhtude või kasutuslugudena. Minu kogemusel on parim variant protsessidiagrammid koos täpsustavate märkustega. Need on ka vähese IT teadmisega inimestele hästi loetavad. Olenevalt projektist võib siiski olla mõistlikum luua kasutajalood või kasutusjuhud.

Kokkuvõtteks

Võibolla imestate, miks ei ole siin nimekirjas „mis“ küsimust? Seda ei olnud etteantud raamistikus – ja kas puhta õnne läbi või mingil muul põhjusel ei olnud ka vaja. Sellele küsimusele vastab nimelt analüütik ise oma tööga. Mõned tellijad annavad üpris täpse nägemuse sellest, mis see tulevane süsteem olema peaks. Siiski peab analüütik selle siis tingimata detailselt läbi analüüsima, kas see on tõesti parim võimalik lahendus. Analüütiku kogemuse najal analüüsiprotsessi läbides jõutakse enamasti mingil määral teistsuguse lahenduseni. Kliendi poolt ette antud lahenduse visioon võib mõnikord kogu analüüsiprotsessi pikemaks ja keerulisemaks muuta; seda eriti siis, kui analüütik jätab seetõttu küsimata “Miks?”.

Need küsimused ei ole ilmselgelt ammendavad. Kõiges saab minna rohkem detailidesse ja projektipõhiselt võib vaja olla küsida väga spetsiifilisi küsimusi. Siiski aitab see raamistik IT-projekti analüüsi käigus katta suuremad välja selgitamist vajavad valdkonnad. Need aitavad mul alustada juttu, kui see mingil põhjusel on raske, ja hoida silme ees seda kõige olulisemat.

Miks teie sellist raamistikku kasutaksite – või ei kasutaks? Kas teil on lihtsaid raamistikke, mis analüüsiprotsessis aitavad? Lisage kommentaaridena siia alla või meie Facebooki või LinkedIn grupis!