Blogi: Ketterän projektin dokumentaatio 3/3 – varautuminen ketterää ylläpitovaihetta varten

Projektin toteutusvaiheen jälkeen lopputulos kannattaa toki dokumentoida varsin perinteisin menetelmin, mutta käyttötarkoitus mielessä pitäen.
Dokumentoi tarpeen mukaan
Mikä on järjestelmän suunniteltu elinikä? Onko jatkokehitystä jo tiedossa? Onko elinkaari niin pitkä, että ylläpitoa ja laajennuksia joutuvat tekemään kokonaan eri henkilöt kuin alkuperäinen toteutustiimi? 15 vuoden käyttöiän, lakimuutoksista ylläpitotarpeita saavan järjestelmän dokumentaation pitää olla erilainen kuin vaikkapa sähköisen asioinnin pilottiprojektin. Jos käyttöikä on lyhyt ja muutostarpeita ei ole, tarvitaanko oikeastaan syvällistä tai mitään dokumentaatiota?

Dokumentointitapa kannattaa suunnitella täysin järjestelmän merkityksen, luonteen ja käytännön tarpeiden mukaisesti.
Strategiadokumentti ajan tasalle
Alkuperäinen strategiadokumentti tai tehtävänanto, visio ja linjaukset kannattaa yhdistää ja liittää järjestelmän taustatiedoiksi. Jos alkuperäisiä tavoitteita on projektin myötä jouduttu muuttamaan, muutokset pitää kuvata. Projektiin osallistuneista kannattaa olla tietoa, jos vaikka 10 vuoden kuluttua jotain asiaa pitää tarkemmin selvitellä.
Tee sanasto
Sanasto on hyvin tärkeä. Termit eivät todellakaan ole yksiselitteisiä eri organisaatioissa. Sanaston avulla ammattilainen kyllä oivaltaa nopeasti, mistä on ollut kysymys.
Vaatimusmäärittely taustadokumentaatioksi
Vaatimusmäärittely tai -luettelo on tärkeä apuväline suunnittelu- ja toteutusvaiheissa, mutta se ei riitä, sovellu tai kelpaa projektin loppudokumentaatioksi. Vaatimusmäärittely kertoo mikä oli ajatus ennen kuin mitään oli tehty.  Se on kuin ostoslista kaupassa käyntiä varten, se ei kerro mitä ruokaa pöydässä lopulta syötiin. Vaatimusmäärittely on tyypillisesti suppea tai laaja kokoelma yksittäisiä, usein varsin irrallisia vaatimuksia, jotka ovat joko toteutuneet tai sitten eivät.
Ylläpitovaiheessa ei ole paljoakaan iloa vaatimusmäärittelystä, jos on pientäkään epävarmuutta siitä, toteutuiko yksittäinen vaatimus ja miten. Vaatimusmäärittely voi toki olla taustadokumenttina mukana, mutta maininnalla sisällön epävarmuudesta, jos niin on.
Kuvaa tietokanta
Tietokannan rakenne ja käsitemalli kannattaa kuvata ainakin periaatteellisella tasolla. Miten koodista tietokantaa käytetään? Miksi on päädytty valittuihin ratkaisuihin? Lähtökohtaisesti käsitteiden ja tietokannassa käytettyjen nimeämisperiaatteiden pitäisi olla sellaisia, että tietokanta itsessään dokumentoi itsensä parhaiten.
Tietokantakuvausten pahin heikkous on, että ne vanhenevat tyypillisesti heti kun ne on laadittu. Dokumentaation uskottavuus kärsii silloin, ja rakenne joudutaan kuitenkin varmistamaan itse tietokannasta. Tarvitseeko todellakin kuvata erikseen, että tietokannan henkilötaulussa oleva kenttä ”sukunimi” tarkoittaa henkilön sukunimeä? Jos tietokannan rakenne ja dokumentaatio kertovat eri tarinaa, aina herää epävarmuus.
Kuvaa rakenne ja toiminnan periaatteet
Sovellusten dokumentaatiossa yleensä mielekkäin lähtökohta on kuvata sen rakenteen ja toiminnan periaatteet. Ne toki saa lähdekoodista selville, mutta selvittelyyn menee usein tunteja aikaa.  Jos edes tämä taso on hyvin dokumentoitu, loppu kyllä selviää lähdekoodista katsomalla.
Kuvaa virhetilanteet ja ratkaisut
Järjestelmän toteutustiimillä on työnsä perusteella vahva käsitys siitä, miten erilaiset virhetilanteet ovat ratkenneet toteutusvaiheessa. Liitetään ihmeessä tämä osaaminen mukaan osaksi dokumentaatiota! Sitä tarvitaan, kun käytön aikana ennemmin tai myöhemmin ongelmia pitää ratkaista. Kehittäjillä on usein ajatuksia siitä, mitä jatkokehitystarpeita on ollut tiedossa. Ehkä ei ole aika riittänyt ja on päädytty vain kirjaamaan idea tulevaisuutta varten. Dokumentaatiossa on tuollaisellekin informaatiolle paikkansa.
Me consultorilaiset luonnollisesti teemme nämä asiat aina asiakkaan toivomusten mukaisesti. Tekemisen tavat kuitenkin muuttuvat ja kehittyvät, siksi ajoittain on hyvä miettiä mikä on paras tapa tehdä asioita.
Lue blogisarjan aiemmat kirjoitukset liittyen ketterän projektin dokumentointiin suunnitteluvaiheessa sekä projektin aikaiseen suunnittelutyön dokumentointiin ja suunnitelmien viestintään toteuttajille.
Tapio Roine
Senior Consultant
etunimi.sukunimi@consultor.fi