Hyvä dokumentaatio on ohjelmistokehityksen kriittisimpiä osatekijöitä. Se on myös liian usein laiminlyöty. Tässä blogissa kaiken softabisneksessä nähnyt ja kokenut hankekonsultti / ratkaisuarkkitehti / #AtoZtyyppi Risto Helin, pohtii hyvän ja huonon dokumentaation merkitystä ja tarjoaa pari ajatusta siitä, miten hyvä dokumentaatio tuotetaan.
Oletko monesti kaivannut lisää tietoa? Todennut, että täytyy jutella jonkun
kaverin kanssa, koska hän tietää miten jotain on toteutettu? Ja kaveri on
matkoilla/lomilla/kiireessä... Mitä sitten tehdään, kun hän, joka tietää, on
tavoittamattomissa ja olisi tulipalo, joka pitäisi sammuttaa? Monesti silloin
otetaan dokumentaatio esille, etsitään ongelma ja katsotaan mitä voidaan tehdä
tulipalon sammuttamiseksi.
Itse olen törmännyt dokumentteihin, joita ei ole tai ovat sellaisia, joissa voisi olla
vähän lisää tietoa. Olen haaskannut aikaa (eli rahaa), kun on pitänyt ymmärtää
jonkin toimintaa puutteellisilla tiedoilla. Joskus dokumentit ovat loogisesti
saatavilla ja joskus niitä saa metsästää kissojen ja koirien kanssa.
Dokumentaatiota miettiessäni ajatukseni menevät sen riittävyyteen ja
löydettävyyteen. Onko mahdollista ottaa dokumentaatio esille ja sen pohjalta
ruveta jatkokehittämään olemassa olevaa järjestelmää? Kai kaikki koodit
löytyvät?
On kallista tehdä jatkokehitystä uudella tiimillä, jos tiimille ei ole tarjota tietoa
järjestelmän toiminnasta. Siinä haaskaantuu turhaa aikaa, kun kehittäjät
miettivät miten jokin toimii, sen sijaan että löytäisivät kokonaisuuden selkeästä
ja kattavasta dokumentaatiosta.
"Hyvä dokumentaatio tehdään silloin kun työ tehdään"
Hyvä dokumentaatio tehdään silloin kun työ tehdään. Jaa, miksi? No kun ihminen
tuppaa unohtamaan asioita. Mikä olisi sitten riittävä laajuus? Sellainen, jolla se
seuraava kaveri voi ottaa ja jatkaa työn tekemistä ja järjestelmän kehitystä, ensi
viikolla tai kymmenen vuoden päästä. Eihän tarkoituksena ole opettaa miten
ohjelmoidaan, vaan mitä jokin osanen tekee ja jos on tehty jotain ”hienompaa”
miksi ja miten se toimii. Ja kun järjestelmä elää, täytyy dokumentaationkin elää
samalla.
Koodin kommentointi on siinä mielessä helppoa, että sen voi laitaa koodin oheen
tai kirjoittaa dokumentaatio kuvineen esim. Markdown-muodossa Githubiin tai
Gitlabiin, jolloin dokumentaatio on automaattisesti versionhallinnassa sekä silloin
siitä on nähtävissä helposti myös muutoshistoria.
Monesti asiakas haluaa dokumentaation Word/PDF muodossa. Kaikki käy, kunhan
tieto on tallella. Valitettavasti usein dokumentaatiosta ajatellaan niin kun
testauksesta. Ei siitä haluta maksaa. Mutta kalliiksi se käy helposti, jos ei työtä
tehdä loppuun.
