Alati ajakohane dokumentatsioon on võimalik

Paljudes IT-meeskondades on juhuslik, killustatud ja aegunud dokumentatsioon. Süstemaatiline ja ajakohane dokumentatsioon aitaks aga IT-arendustes hoida ühtset joont, efektiivselt probleeme lahendada ja uutel inimestel kiiremini sisse elada. Ma olen tihti kuulnud, et agiilsetes projektides ei olegi võimalik dokumentatsiooni ajakohasena hoida, ja seega ei ole seda mõtet luuagi (kirjutasin sellest varem ka artiklis Lükkame ümber 6 müüti dokumenteerimisest).

Mina ütlen, et on küll võimalik!

Pea igas meeskonnas on dokumentatsioon minu liitumise hetkel olnud killustatud, aegunud või täiesti puudu. Olen näinud süsteeme, kus sama funktsionaalsust oli mitmel korral ja erinevalt arendatud. Olen pidanud meeskonna rahvapärimuse järgi soovitud olukorra kirjeldust taastama. Ja muidugi olen pidanud puudulike dokumentatsiooni põhjal arendusi planeerima. See on üks korduv frustratsioon!

Selle muutmiseks olen katsetanud mitmeid lähenemisi. Mina olen enda jaoks leidnud põhimõtted, mis aitavad dokumentatsiooni luua, hallata ja ajakohastada loomuliku protsessi osana ka agiilsetes meeskondades.

Miks IT-dokumentatsioon on nii tihti aegunud?

Tihti kujutatakse dokumenteerimist traditsioonilise kose mudelina: kõigepealt tehakse analüüs, seejärel süsteemidisain, arendus ja testimine. Kui süsteem paigaldatakse, siis on ka dokumentatsioon valmis. Reaalsuses ei käi IT-arendus aga tänapäeval lineaarselt. See on paindlik, paralleelne ja väikestest tükkidest koosnev. Pidevalt muudetakse ka kasutusel olevaid süsteeme. Dokumenteerimist tuleb agiilse protsessi jaoks kohendada.

Agiilsetes meeskondades on dokumentatsiooni olemas tavaliselt ülesandepüstituseks või ainult siis, kui seda küsitakse. Selles ei tehta muudatusi, mis arenduse käigus vajalikuks osutusid, ja seda ei seota süstemaatiliseks dokumentatsiooniks. Erinevate Confluence’i lehtede rägastikus kaob lugejal kergesti arusaam, milline on päriselt valminud lahendus, mis on alles plaanitud või mis on tegelikult juba kõrvale heidetud uitmõte.

Selliselt jõutaksegi olukorda, kus süstemaatilist ja usaldusväärset dokumentatsiooni ei ole. Inimeste vahetumisel kaob ka kogu teadmine selle kohta, kuidas lahendus on üles ehitatud ja miks just selliselt. Pole siis ime, kui dokumentatsiooni suhtes selline vastumeelsus on!

Kuidas ajakohast dokumentatsiooni saavutada?

Igale meeskonnale saad sobiva lahenduse välja töötada, kui mõtled läbi järgmised küsimused:

1. Kuidas eristad ajakohast (AS-IS) ja tulevikulahendust (TO-BE)?

Igaüks, kes dokumentatsiooni loeb, peaks aru saama, millise lahenduse kohta see käib – kas see on valmis või alles loomisel; ja selleks tuleb leida oma tava. Olen selle lahendusena näinud erinevaid lähenemisi:

• ajakohane ja tulevikulahendus on eraldi dokumendid, kus on selgelt näha, mis olukorda see kirjeldab;
• tulevikulahendust kirjeldav osa on ajakohases dokumentatsioonis värviga märgistatud;
• iga muudatusega luuakse uus versioon dokumendist. Vastupidiselt teistele peetakse järge hoopis selle üle, millisele dokumendile vastav lahendus on töökeskkonda jõudnud.

Kõik need võivad selguse luua, aga ükski neist ei sobi igasse olukorda. Kõige halvem variant on see, kui sama meeskonna raames on kasutusel erinevad praktikad – siis on segadus kerge tekkima!

2. Mis seisundile ajakohane dokumentatsioon vastama peab?

Palju räägitakse aegunud dokumentatsioonist, aga mis hetkel see „aegub“ võib olla igas meeskonnas erinev. Dokumentatsiooni luues kirjeldatakse tavaliselt eelkõige tulevikuvisiooni, aga mis hetkel saab lugeda visiooni reaalsuseks? Kas siis kui ta on arendaja poolt valmis programmeeritud, testkeskkonnas üle kontrollitud või alles siis, kui ta on töökeskkonda viidud?

Erinevates meeskondades ei pruugi see vastus olla sama. Ainult siis, kui teed selle kohta selge kokkuleppe, saad kindel olla, et kogu meeskond saab dokumentatsiooni tähendusest samamoodi aru.

3. Kuidas ajakohastamine toimub?

Eelmisest punktist said vastuse, mis hetkel see toimuma peaks. Kindel saad olla dokumentatsiooni ajakohastamises ainult siis, kui see on osa regulaarsest tööprotsessist.

• Tegevusel peab olema kindel vastutaja. Erinevates meeskondades võib selleks olla roll tooteomanikust ja arendajani.
• Vastutaja peab saama ajakohastamise teostamiseks meeldetuletuse. Minu soovitus on luua kindel märguanne – olgu see eraldi ülesanne või kalendri meeldetuletus -, et uuendamine õigel ajal tehtud saaks ja töö ei kuhjuks.

Kui eelnev on lahendatud, siis on dokumentatsiooni uuendamine kiire ja lihtne tegevus. Minu jaoks annab see ka teatud lõpetatuse ja rahulolutunde, et mingile ülesandele on joon alla tõmmatud.

Teadlikult tegutsedes on alati ajakohane dokumentatsioon võimalik

Kuigi põhimõtted on üldised, ei ole ühte kindlat vastust, mis sobiks alati ja igale meeskonnale – kõigel on omad plussid ja miinused. Räägin neist pikemalt oma peagi ilmuvas raamatus “Optimaalne dokumentatsioon: kasulik, ajakohane ja mugav” ja minu mitu korda aastas toimuva „Äri- ja süsteemianalüüsi kursuse“ esimesel päeval. Seal annan ka täpsemaid soovitusi, kuidas enda meeskonnale kõige paremini sobiv lahendus leida.

Julgen kinnitada, et kui need põhimõtted on meeskonnas teadlikult läbi mõeldud ja rakendatud, saab dokumentatsioonist väärtuslik tööriist, mida saad alati usaldada. Minu projektides see nii on!