Kuidas kirjutada kasulikku ja lihtsasti hallatavat dokumentatsiooni?
Kui oled kunagi keset projekti mõne dokumendi lahti teinud ja mõelnud: „Sellest pole mingit kasu ja see on ilmselt aegunud” — või pole leidnudki ühtegi dokumenti, mis annaks sulle lahendusest ülevaate —, siis sa ei ole üksi. Paljud IT-tiimid arvavad, et dokumentatsiooni loomine võtab liiga kaua aega, keegi nagunii ei loe seda ning see aegub praktiliselt kohe. Pigem peaks nad rohkem küsima: „Kuidas kirjutada kasulikku ja lihtsasti hallatavat dokumentatsiooni?”
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.