On myönnettävä, että liian monesti olen lukenut epäonnistunutta dokumentaatiota – sekä omaani että jonkun muun kirjoittamaa. Mikäli dokumentoinnin laatuun ei panosteta, olen aika vakuuttunut siitä, että se tuskin onnistuu edes sattumalta. Ohessa siis neljä vinkkiä laadukkaampaan dokumentaatioon.

1. Tunne kohdeyleisösi

Dokumentointi on viestintää ja siinä pätee tuttu sääntö: mitä paremmin tunnet kohdeyleisösi, sitä todennäköisemmin sanomasi ymmärretään oikein.

On hyvä pohtia etukäteen, millainen osaamistaso dokumentaation lukijalla voidaan olettaa olevan? Suomalaisille on helppo antaa saunomiseen ohje: “jos tulee kylmä, heitä löytyä”. Jos sama ohje annetaan filippiiniläiselle, ymmärtääkö hän mitä tarkoittaa “heittää löylyä”? Olisiko edes “heitä vettä kiukaalle” -ohje riittävä? Koska eihän tarkoitus ole heittää vettä varsinaisesti kiukaalle vaan kiuaskiville. Toisaalta suomalaiselle näin tarkka ohjeistus vaikuttaa saivartelulta ja saa todennäköisesti hylkäämään koko ohjeen.

2. Ajattele algoritmisesti

Hyvä dokumentaatio lähtee monesti syntymään jo ennen kuin on riviäkään koodia kirjoitettu. Itse toisinaan aloitan suunnittelulla uuden toiminnallisuuden koodauksen. Kirjoitan koodin kommentteihin, mikä on esimerkiksi funktion tavoite. Tämän jälkeen jatkan suunnittelua kommentoimalla ne osatehtävät, joita vaaditaan tavoitteen täyttymiseksi. Kun minulla on kommenteissa edes jonkinlaiset tienviitat etenemissuunnasta, alan koodaamaan. Näin koodille syntyvät kommentit osittain itsestään.

Tällaisessa työskentelytavassa auttaa algoritminen ajattelutapa: isomman tehtävän pilkkominen pienempiin osiin. Tämä auttaa myös kehittäjää avun kysymisessä, sillä ongelmatilanteissa on vaikea nähdä puita metsältä ilman algoritmista lähestymistapaa. Ilman sitä kaikki tekeminen hahmottuu vain yhtenä isona massana ja myös avun antaminen on hankalampaa, koska tarkempi konteksti ei ole tiedossa. Jokainen voi miettiä, kumpaan seuraavista kysymyksistä on helpompi tarjota apua: “En onnistu kahvinkeittämisessä. Voitko auttaa minua?” vai “Yritän keittää kahvia. Onnistuin mittaamaan oikean veden määrän, mutta en löydä mistään kahvimittaa, jotta voisin mitata kahvipurujen määrän. Voitko auttaa minua?”

3. Kommentoi koodisi

Laadukas ja selkeä koodi dokumentoi monesti itsensä varsin hyvin ja vastaa mitä-kysymykseen. Toisinaan oleellista on vastata myös miksi-kysymykseen. Miksi koodi itse asiassa edes on olemassa? Miksi on tehty valinta, että asia on tehty tavalla X?

Koodin kommentoinnissa ei tulisi myöskään unohtaa versionhallinnan commit-viestejä, sillä ne ovat oleellinen osa koodin ja tekemisen dokumentointia. Erityisen tärkeäksi olen havainnut ne sivustojen ylläpitovaiheessa. Esimerkiksi omassa yrityksessämme on tapana aina jokaisen bugikorjauksen kohdalla laittaa commit-viestiin linkki tukitikettiin, jossa ongelma on kuvattu. Tällöin dokumentoituu paremmin se konteksti, jossa esimerkiksi jonkin funktion toiminnallisuutta on muutettu. Jos myöhemmin tulee tarve uudelleenarvioida toiminnallisuutta, voimme palata commit-viestissä viitattuun tukitikettiin ja arvioida sen valossa vieläkö bugikorjaus on ajankohtainen.

4. Opettele dokumentoimaan myös jalanjälkesi

Dokumentoinnin tarve ei monestikaan liity pelkästään koodiin tai teknisiin ohjeistuksiin. Varsinaisen tuotetun koodin lisäksi (tai joskus jopa pelkästään) olisi oleellista pystyä dokumentoimaan myös omat jalanjälkensä. Erityisen tarpeelliseksi tämä tulee silloin, kun jokin asia ei onnistu ja kehittäjä kysyy neuvoa toisilta kehittäjiltä. Tällöin on oleellista se, että osataan viestiä mitä on jo yritetty. Analogiaa voi ottaa ihan elävästä elämästä. Jos eksyt metsäretkellä, avun saamista helpottaa kummasti, kun osaat kertoa edes suurpiirteisesti, mistä olet tulossa, mihin olet matkalla ja millaista polkua olet tähän mennessä kulkenut.

Jos kehittäjä ei dokumentoi omia jalanjälkiään mihinkään, ne valitettavan usein ovat kuin jäätelö kesähelteellä: hetken käsin kosketeltavan konkreettinen, sitten vain märkä läntti kuumalla asfaltilla. Ja kehittäjällä paha mieli.