Ohjelmistoprojekteihin liittyy monenlaista dokumentaatiota. On projektidokumentaatiota, esimerkiksi projektisuunnitelma, palaverimuistioita, riskien hallinnan dokumentaatiota ja muutoshallintadokumentteja. On erilaisia manuaaleja, esimerkiksi käyttöohjeita, kehitysympäristön käyttöönotto-ohjeita tai rajapintakuvauksia. On vaatimusmäärittelyä, arkkitehtuurikuvausta, teknistä määrittelyä, toiminnallista määrittelyä, testisuunnitelmaa, testiraporttia, käyttöliittymäsuunnitelmia, joko riittää? Ehtiikö projekteissa muuta tehdäkään kuin kirjoittaa ja ylläpitää dokumentteja? Joku voisi jo kysyäkin, että kirjoitatteko te softaprojekteissa pelkästään dokumentteja, ehditäänkö sitä softaa koodata ollenkaan? Tai kummastako asiakas on valmis maksamaan? No tässä kohdin voisi heittää vastakysymyksen, onko dokumentointi ja koodaaminen toisensa poissulkevia? Ja sen vastaus on selvä, ei tietenkään ole, dokumentointi on kiinteä osa myös ohjelmistoprojekteja. On huomioitava, että ohjelmistojen dokumentaation määrään tai sisältöön ei ole olemassa yhtä ainutta absoluuttista totuutta, se on aina tapauskohtaista, mitä tarvitaan. Tämä kirjoitus tarjoaa aiheeseen yhden näkökulman. Tietotekniikan dokumentaatio -kurssin ohjelmistot-osuudessa yhtenä vaihtoehtoisena tehtävänä oli kirjoittaa essee otsikolla Ohjelmistojen dokumentointi. Kaksi VAMKin toisen vuoden TT-opiskelijaamme, Henna Metsälä ja Topias Elomäki, pohtivat asiaa mielenkiintoisista näkökulmista. Näitä näkökulmia on tuotu esille myös tässä tekstissä.
Agile manifeston yksi ohjenuorista on, ”Working software over comprehensive documentation”, eli kaikenkattavan dokumentaation sijaan tulisi panostaa toimivaan ohjelmistoon. Manifesto on tavallaan oikeassa, mitä hyötyä on dokumentaatiosta, jos sovellus ei toimi? Mutta antaako se meille luvan jättää dokumentaatio tekemättä? Ei tietenkään anna, vaikka siihen aina välillä kuuleekin vedottavan. Tuo Agilen ohjenuora tarkoittaa sitä, että projekteissa tulisi kirjoittaa vain sellainen dokumentaatio, jolle on lukija, tehdä sellainen dokumentaatio, jota joku tarvitsee. Elomäen tiivistämänä, ohjelmistojen dokumentointi on tärkeä tapa välittää ohjelmistoon liittyviä tärkeitä seikkoja ja taustatietoja tuleville käyttäjille ja kehittäjille. Olemassa oleva dokumentaatio tarjoaa myös usein ratkaisuita yleisimpiin ongelmiin, sekä asennukseen liittyviin pulmiin.
Dokumentointi tarkoittaa siis moniakin asioita. Kyse ei ole pelkästään satasivuisten word-dokumenttien kirjoittamisesta, vaan enemmän siitä että dokumentaatio on siellä missä sitä tarvitaan. Kehitysympäristön pystytysdokumentaatio on saatavilla siellä missä koodikin on. Sovelluksen tarjoamista rajapinnoista tehdyt kuvaukset on saatavilla niihin tarkoitetuissa järjestelmissä. Elomäki niin ikään näkee dokumentoinnin tyylejä ja paikkoja olevan erilaisia, toiset saattavat luoda hienot nettisivut johon on upotettu ohjeet sekä ohjelmiston käyttötarkoitus itsessään, ja toisissa se voi olla pieni kommentoitu osuus ohjelman lähdekoodin yläreunassa. Vaikka tyylejä on monia, käyttötarkoitus pysyy aina samana: Dokumentointi pyrkii selvittämään ohjelmiston käyttäjälle, muokkaajalle tai muulle vastaavalle sen ominaisuudet, versiohistorian, mitä ohjelmistolla tulee tehdä, ja mitä mahdollisesti ei, tai yli päätään mitä ohjelmiston tekijä on koittanut tarkoittaa. Agilen, eli ketterien kehitysmallien myötä esimerkiksi vaatimusmäärittelyissä on siirrytty paljolti käyttäjätarinoiden kuvaamiseen. Käyttäjätarinankin tavoite on vain ymmärtää mitä asiakas oikeasti haluaa, ja tarinoiden myötä on helpompaa päästä samalle viivalle, puhumaan asiakkaan kanssa samaa kieltä. Käyttäjätarina on siis yksi tapa kuvata vaatimus, se vastaa kysymyksiin kuka, mitä ja miksi. Esimerkiksi verkkokauppaprojektissa yksi käyttäjätarina voisi olla ”Verkkokaupan käyttäjänä haluan lisätä tuotteen ostoskoriin, jotta voisin tilata sen”. Toteutusvaiheessa nämä käyttäjätarinat käännetään toteutettaviksi tehtäviksi, eli taskeiksi. Taskille kirjataan se mitä konkreettisesti tulee tehdä, jotta vaatimus saadaan täytettyä. Itse koodauksessa ohjelmistojen dokumentaatio yksinkertaisimmillaan on sisäänrakennettuna koodissa: muuttujat ja funktiot nimetään siten, että niiden käyttötarkoitus on itsestään selvää, tällöin ei tarvitse enää erikseen kuvata, mihin niitä tarvitaan.
Metsälä nostaa tekstissään esiin niin dokumentaation hyötyjä kuin haasteitakin. On selvää, että dokumentoinnista on paljon hyötyjä, varsinkin hyvin tehdyssä dokumentoinnissa uusien kehittäjien on helppo siirtyä mukaan projektiin, kun kaikki on kirjoitettuna ylös. Dokumentointi auttaa myös käyttämään koodia uudelleen, sillä vaiheet ovat kirjattu tarkasti ylös. Dokumentointi auttaa myös itse kehittäjiä, kun koodaamisvirheet vähentyvät eikä silloin koodissa esiinny yhtä paljon bugeja kuin ilman dokumentaatiota. Dokumentaatiossa on kuitenkin myös ongelmia. Suurimpina haasteina on olemassa olevan dokumentaation ylläpito, se vie aikaa ja resursseja pois muusta. Dokumentaatioiden tekeminen ei aina ole kaikkien mielestä miellyttävää tehdä tai niihin ei ole tarvittavia taitoja kuten muiden kirjoittaman lähdekoodin ymmärtämistä. Aloittavana ohjelmistokehittäjänä on vaikea tietää tarkalleen kuinka paljon ja millaisia dokumentaatioita ylipäätään tarvitaan, tai miten paljon dokumentoinnille voidaan projekteissa varata aikaa, kun huomioidaan ihmiset, jotka lukevat ja käyttävät projektin dokumentaatiota. Oikeassa elämässä, eli työelämässä, tämä dilemma on onneksi ratkaistavissa. Aina löytyy joku kokenut kehittäjä, jolta voi kysyä apua ja joka myös tukee aloittavaa kehittäjää. Koodirivit katselmoidaan kokeneiden kehittäjien toimesta, ja näissä katselmoinneissa tarkistellaan myös dokumentaatiota, onko esimerkiksi koodi kommentoitu riittävällä tasolla.
No mitäs haastetta tässä sitten on? Yrityksissä on prosessit, ja kun niitä vain noudattaa, niin kaikki tulee tehtyä? Ideaalimaailmassa kyllä, projekteista löytyy kaikki tarvittava dokumentaatio, sitä päivitetään aina tarvittaessa ja sen ajantasaisuudesta huolehditaan. Oikeassa elämässä? Ei se ole ihan näin ruusuilla tanssimista. Mitä esimerkiksi sitten kun on se iänikuinen kiire? Aikataulut ovat tiukkoja, toiminnallisuus on kehitetty, mutta dokumentaatio pitäisi vielä päivittää? Me kehittäjätkin olemme ihmisiä, työpäiviä leimaa yleensä kiire ja oman tekemisen jatkuva priorisointi. On inhimillistä, että dokumentaatio jää joskus päivittämättä. Se ei kuitenkaan tee siitä sallittua. Mikään ei ole turhauttavampaa kuin dokumentaatio, joka ei ole ajan tasalla. Projekteissa on oltava prosessit ja laadunvarmistus siihen, ettei dokumentaation tekeminen ja päivittäminen pääse unohtumaan. Kehittäjille on varattava aikaa siihen, että dokumentaatio tehdään. Dokumentaation päivittämisen varmistamiseen on erilaisia toimivia käytäntöjä. Taskeilla voi olla esimerkiksi dokumentointi-status. Käytännössä jokainen toteutettu taski on dokumentointi-statuksella niin kauan, että dokumentaatio on päivitetty. Ajantasainen dokumentaatio ei hyödytä pelkästään kehittäjätiimiä, vaan luonnollisesti se hyödyttää myös asiakasta. Kun tiedetään mitä on tehty, miksi jotakin on tehty, miten ympäristöt päivitetään, miten kehitysympäristön saa pystyyn, säästää se aikaa, vaivaa ja turhautumista projektissa. Otsikon kysymykseen, dokumentaation tekeminen voi joskus tuntua pakkopullalta, mutta kun projektiin tulee uusia ihmisiä tai pitkien aikojen kuluttua ohjelmistoon tehdään muutoksia, on dokumentaation olemassaolo kuin suklaapäällysteinen kermakarkki, nätti päältä ja suussa sulava sisältä, kaikkien haluama. Olemassa oleva ja etenkin ajantasainen dokumentaatio on koko projektin ja sitä myöten koko yrityksen etu!
