Hei taas,

Jotain mitä olen jo pidemmän aikaa eräässä uudessa projektissani ihmetellyt on tapa, miten ohjelmointiprojekteissa kaikki muu kansipahvien suunnittelua ja wrap-up-saunaillan organisointia myöten tuntuu välillä menevän kunnollisen dokumentin kirjoittamisen edelle. Tietysti ymmärrän sen, että keskeneräisen kehitysversion dokumentit elävät, ja jos alusta muuttuu niin sitten kaikkia dokumenttejä pitäisi päivittää, muodostaen ylimääräisen tehtävän joka olisi voitu välttää kirjoittamalla dokumentaatio ensimmäisestä ”release candidate”-versiosta.

Monesti kuitenkin käy niin, että lataan jonkin moduulin tai koitan selvitellä mistä metodi oikein on keksinyt vaatia kaiken mahdollisen tupleina, tai vaihtoehtoisesti haluaisin käyttää jotain umpimielistä koodia tekemään monimutkaisia asioita. ”Älä keksi pyörää uudestaan” on mielestäni ihan hyvä periaate; ikävä kyllä alkuperäisen keksijä jättää monesti kertomatta mihin tätä uutta hienoa pyörää voisi käyttää.  Helpot tapaukset on niitä, joissa API on kuvattu skriptillä pureskeltuna generoituna tekstinä, joka ei aukea oikeastaan sen enempää kuin itse lähdekoodi. Kehittäjille ehkä hyödyllinen, käyttäjille vihamielinen. Pahimmillaan olen nähnyt tilanteita, missä kaksi, jopa kolme, dokumenttia ovat keskenään ristiriitaisia ja neuvovat tekemään asiat eri tavoin, tai painottavat täysin eri asioita. Lopulta usein tuleekin tunne, että on kokoamassa pelkkiin faktoihin perustuvaa kuvausta urheilukilpailusta haastattelemalla ulos heitettyjä humaltuneita katsojia, tai olevansa loukussa ”yksi valehtelee aina, yksi joskus ja loput puhuu totta”-tyyppisessä logiikkatestissä.

Mutta joo. Jo ohjelmistotekniikan peruskurssilla opetetaan, että ainoa asia joka on huonompi kuin puutteellinen dokumentointi on virheellinen dokumentointi, ja että kaikista viisain eläin on majava joka sukeltaa sateelta suojaan. Dokumentaatio ja käyttöohjeet voivat monesti vaikuttaa turhalta lisätyöltä, mutta ne eivät olekkaan tarkoitettu kehittäjille itselleen, vaan niille jotka käyttävät heidän tekemiään työkaluja. Ja vaikka ajatus vahingon kiertämään laittamisesta voikin houkuttaa, olisi siinä tapauksessa harkitsemisen arvoista ennemmin ryhtyä vaikka autokauppiaaksi.

Täältä tähän,

Jussi Kasurinen