Tiedät varmaan mitä dokumentointi ohjelmistoprojektissa tarkoittaa? Ja olet kuullut ketteristä kehitysmenetelmistä? Siltä varalta, että on päässyt livahtamaan ohi, dokumentaatiolla tarkoitetaan yleensä kirjallista – muulla kuin ohjelmointikielellä kirjoitettua – kuvausta ohjelman tai sen osan toiminnasta. Ketterillä kehitysmenetelmillä viitataan joukkoon erilaisia projektinhallinnan menetelmiä, jotka juontavat juurensa vuosituhannen vaihteessa julkaistuun manifestiin (Agile Manifesto). Tunnetuimpia ja eniten käytettyjä menetelmiä lienevät tällä hetkellä Scrum ja Kanban, vaikkei minulla mitään vedenpitävää tilastotietoa väitteeni tueksi olekaan.
Mutta oletko koskaan kuullut väitettä ”koska olemme ketteriä, emme tee dokumentaatiota”? Niin minäkin.
Entä jos se ei olekaan näin? Mitä jos dokumentaation puuttumisella ei olekaan mitään tekemistä ketterien kehitysmenetelmien kanssa, vaan kyse onkin huonoista kehitystavoista, matalasta vaatimustasosta tai laiskuudesta?
Ketterää periaatetta
Vuonna 2001 seitsemäntoista ohjelmistoalan ammattilaista kokoontui Snowbird:n vapaa-ajan keskuksessa Utah:ssa Yhdysvalloissa keskustelemaan kevyemmistä ohjelmistotuotannon prosesseista. Tämän kokoontumisen tuloksena julkaistiin manifesti – Agile Manifesto.
Manifesti perustuu neljään periaatteeseen:
Individuals and Interactions over processes and tools
Working Software over comprehensive documentation
Customer Collaboration over contract negotiation
Responding to Change over following a plan
Näiden periaatteiden pohjalta on luotu kirjava joukko erilaisia menetelmiä, joissa on yhtäläisyyksiä, mutta ratkaisevat osan kaikille projekteille yhteisistä haasteista eri tavalla.
Ketterät periaatteet kehitettiin vastauksena alati kasvavien, nopeasti muuttuvien ohjelmistokehitysprojektien haasteeseen.
Tarpeettoman monta ohjelmistoprojektia epäonnistui, koska vaatimusmäärittely- tai dokumentointivaiheen jälkeen tuote ei enää vastannutkaan alkuperäistä tarvetta. Ei ollut tavatonta, että kehitysvaiheeseen selvinnyt projekti oli joko paisunut hallitsemattomaksi kaaokseksi tai asiakkaan tarpeet olivat muuttuneet siten, että alkuperäinen vaatimusmäärittely ei enää pitänyt paikkaansa.
1990-luvun lopussa oli siis tarve löytää uusia ja kevyempiä tapoja ohjelmistoprojektien läpivientiin. Siihen tarpeeseen eri tahoilla itsenäisesti kehittyneiden menetelmien pohjalta luotu manifesti pyrki vastaamaan.
Kun dokumentointi ei maistu
Itsekin ohjelmistoalan toimijana ymmärrän hyvin, että dokumentaation kirjoittaminen ei ole sitä kaikista seksikkäintä hommaa. Usein kyse on itseään toistavasta tehtävästä, minkä omanarvontuntoinen ohjelmistokehittäjä siirtää helposti laatikkoon ”ei kuulu minun tasoiselle tekijälle” tai yksinkertaisesti jättää tekemättä saatesanoilla ”Hyvä koodi dokumentoi itsensä”.
Tässä kohtaa manifesti astuu kuvaan. Toinen periaate – Working software over comprehensive documentation – tarjoaa täydellisen tekosyyn dokumentaation sivuuttamiselle. Sanotaanhan se tuossa edellä varsin selvästi, että toimiva koodi menee aina dokumentaation edelle. Vai kuinka?
Tästä (virheellisestä) tulkinnasta on syntynyt käsitys, että ketterät menetelmät ja dokumentaatio eivät mahdu samaan toimistoon.
Dokumentaation absoluuttinen määrä ei kuitenkaan mittaa projektin onnistumista millään tavalla, ei suuntaan eikä toiseen. Dokumentoimatta jättäminen ei myöskään tee organisaatiosta yhtään ketterämpää.
Lukija määrää tarpeen
No mitä muka sitten pitäisi dokumentoida, kun ketterät periaatteet sanovat toimivan softan olevan dokumentaatiota tärkeämpää?
Avainsana on comprehensive, mikä tarkoittaa laajaa tai kattavaa ja tässä nimenomaisessa yhteydessä kaiken kattavaa. Se ei ole synonyymi sanalle any (mitään, yhtään). Oikeasti toinen periaate tarkoittaa, että toimiva ohjelmisto on kaiken kattavaa dokumentaatiota tärkeämpää, ei suinkaan kaikkea dokumentaatiota tärkeämpää.
Ehdotonta rajaa sille, mitä dokumentaatiota pitäisi tehdä, ei ole helppo vetää. Tapauskohtaisia eroja on sikäli paljon. Nyrkkisääntönä: vältä vain sellaisen dokumentaation kirjoittamista mitä kukaan ei lue. Toisin sanoen, jos voidaan odottaa, että dokumentaatiolle löytyy lukija, kannattaa sen kirjoittamista harkita. Joissain tapauksissa myös vaatia.
Mutta miten sen voi etukäteen tietää, mille dokumentaatiolle löytyy lukija? 100% varmuudella ei mitenkään. Kuitenkin haastattelemalla kehittäjiä varmasti löytyy yhtäläisyyksiä tapauksista, missä dokumentaatiosta olisi ollut hyötyä, mutta sellaista ei oltu tehty.
Dokumentaation tarpeita
Tarjoaako ohjelmistosi avoimen rajapinnan? Lienee odotettavaa, että joku (sisäinen tai ulkoinen) taho haluaa sovellukseesi kytkeytyä, niinpä rajapintakuvaukselle voidaan olettaa löytyvän lukija.
Onko sovellustasi tarkoitus kehittää toiminnallisuus kerrallaan pitkän ajan kuluessa? Onko odotettavissa, että uudet toiminnallisuudet eivät ole itsenäisiä, vaan liittyvät ohjelmiston aiempaan toiminnallisuuteen? Väitän, että ennemmin tai myöhemmin arkkitehtuurin dokumentaatiolle löytyy lukija, oli syynä sitten uuden ominaisuuden kehittämisen tai alkuperäisen toiminnallisuuden päivittämisen synnyttämä muutos.
Muitakin esimerkkejä varmasti on. Vartin keskustelulla kehittäjien kanssa kahvin ääressä saat varmasti ajatuksia oman organisaatiosi ja tuotteesi erityispiirteistä.
Voisiko allergiaoireita lieventää?
Dokumentaation tarve ei tokikaan poista sen tekemiseen liittyviä allergioita. Lisäksi kuvaukset vanhenevat, ja jonkun täytyisi pitää ne ajan tasalla. Virheellinen dokumentaatio on lähes yhtä suuri ongelma kuin puuttuva dokumentaatio, joissain tapauksissa jopa pahempi ongelma.
Dokumentaation tuottamiseen on onneksi monia helpottavia työkaluja. Rajapintakuvausten tekemiseen löytyy tarkoitukseen suunniteltuja kieliä ja sovelluksia (esim RAML, Swagger), joiden avulla interaktiivisten, helposti ymmärrettävien kuvausten tekeminen ei ole enää samanlainen ponnistus kuin ennen.
Dokumentaatio voi olla myös monessa muodossa. Tarvitseeko järjestelmäsi arkkitehtuurikuvauksen? Valitkaa tiimistänne se, joka tuntee aiheen parhaiten. Pyytäkää häntä esittämään tuotteen arkkitehtuuri valkotaulun ja tussin avulla muulle tiimille 10 minuutissa. Varatkaa 5 minuuttia jatkokysymyksiin. Kuvatkaa koko homma videolle (älypuhelimen kamera riittää mainiosti) ja kas kummaa, arkkitehtuurikuvaus on olemassa. Bonuksena, dokumentaatio on näin nuoremmille kehittäjäsukupolville helpommin sulatettavassa muodossa.
Valintakysymys
Dokumentoinnin ei tarvitse olla se mörkö, jota kaikki pelkäävät. Eivätkä ketterät menetelmät saa olla tekosyy dokumentaation puuttumiselle. Ohjelmistokehittäjille dokumentaatio on kyllä (ymmärrettävästi) allergeeni mutta oikeilla työkaluilla oireita voi lieventää.
Loppu on kiinni organisaation vaatimustasosta.