dokumentaatio_suunnittelumallit_blog

Tämä teksti on jatkoa aikaisemmin julkaistulle tekstille, joten kannattaa lukea se ensin.

Edellisessä osassa puhuttiin erilaisista hyödyistä, kun käytetään suunnittelumalleja dokumentoinnin apuna. Tässä osassa näytetään, kuinka projektin käytännöistä saadaan luotua suunnittelumalleja. Kannattaa huomioida, että vaikka projektit ja tilanteet ovat erilaisia, suunnittelumallien pitäisi olla yleiskäyttöisiä, kestäviä ja käytettävissä myös oman projektin ulkopuolella – helposti muuttuvat yksittäistapausten yksityiskohdat voi dokumentoida muuten.

Suunnittelumallien on tarkoitus kuvata olemassa olevia käytäntöjä, jolloin niihin ei kannata laittaa osioita, joita ei ole oikeasti käytössä tai itse kokeiltu. Lopuksi, maailmalla on varmasti dokumentoitu vastaavia tai ainakin asiaa sivuavia suunnittelumalleja, joten niiden tutkiminen ja niihin viittaaminen on olennainen osa oman suunnittelumallin luontia.

Esipuhe

Dokumentointia varten harvoin riittää yksi suunnittelumalli. Siksi dokumentaatio koostuu käytännössä joukosta suunnittelumalleja, joista jokainen kuvaa yhden, tarkasti rajoitetun ongelman käyttäen määrättyä tekstimuotoa. Kaikkien saman dokumentin mallien on syytä noudattaa samaa muotoa. Näin varmistetaan, että lukija löytää välittömästi haluamansa kohdan tekstin seasta. Mallit kannattaa tallentaa esimerkiksi mallikieleksi,  jolloin niihin on helppo viitata myöhemmin.

Erilaisia muotoja suunnittelumalleja varten on esitelty osoitteessa http://c2.com/cgi/wiki?PatternForms. Sujuvaa tekstiä saa käyttämällä alkuperäistä Alexandrilaista muotoa. Tällaisen suorasanaisen muodon käyttö vaatii kuitenkin kirjoittajalta huomattavasti itsekuria ja kokemusta, joten aloittelijan kannattanee valita mielummin jokin rakenteinen, jopa taulukkomuotoinen muoto, jossa on selvästi erotellut osat: konteksti (context), ongelma (problem), voimat (forces) ja ratkaisu (solution). Lyhyesti sanottuna konteksti kertoo tilanteen, jossa mallin kuvaama ongelma esiintyy ja ongelmassa kuvataan tilanne, jonka malli ratkaisee. Voimat puolestaan kertovat, milloin valittua ratkaisua kannattaa käyttää ja antavat ratkaisulle reunaehdot. Näistä eri osista myöhemmin lisää.

Esimerkki

Suunnittelumallin luomista varten käytän yksinkertaista esimerkkiä. Esimerkki kertoo tilanteesta, jossa projektiryhmä on huomannut, että uuden työntekijän on helpompi olla osa ryhmää, kun ryhmä on normaalin teknisen dokumentaation lisäksi dokumentoinut myös tietoja ryhmästä itsestään. Myös muilla projektiryhmillä oli aikaisemmin ollut vastaavia kokemuksia. Tämä vuoksi projektiryhmä on päättänyt dokumentoida uuden työntekijän perehdyttämisen suunnittelumalliksi. Kannattaa huomata, että keskityn tässä kirjoituksessa nimenomaan mallin luomiseen, joten mallin tekstiä ei välttämättä kannata ottaa esikuvana hienosta perehdyttämisestä.

Seuraavaksi käyn yleisesti läpi jokaisen muodon osan merkityksen ja sisällön. Jokaisen osan jälkeen kursiivilla on kirjoitettu vastaava kohta esimerkkisuunnittelumallista. Viittauksen muihin suunnittelumalleihin on kirjoitettu ISOLLA. Näiden viitattujen mallien ratkaistavat ongelmat on listattu Taulukossa 1.

Taulukko 1: Esimerkissä viitatut suunnittelumallit
Malli Ongelma
YLEISET KÄYTÄNNÖT Yrityksiin kertyy hiljaista tietoa erilaisista käytännöistä. Tämä tieto pitäisi saada levitettyä tehokkaasti työntekijöille.
TYÖPISTE Työntekijän fyysinen sijoittuminen työpaikalla vaikuttaa hänen työtehoonsa projektissa ja yrityksessä. Kuinka sijoittaa työntekijän työpiste, jotta työteho olisi optimaallinen?
MENTOR Isossa organisaatiossa uuden henkilön on vaikea tietää keneltä kysyä tarvittaessa neuvoa. Tämä aiheuttaa tarpeettoman suuren kynnyksen ja vähentää työtehoa.

Konteksti

Kontekstin tarkoituksena on kuvata se tilanne, jossa suunnittelumallin ongelma esiintyy. Useassa suunnittelumallissa voi olla sama ongelma, mutta eri lähtötilanne. Esimerkiksi tietyn ongelman ratkaisu voi riippua siitä, toteutetaanko sulautettua järjestelmää vai www-palvelinta. Eli vaikka kahden tilanteen ongelma olisikin sama, sama suunnittelumalli ei välttämättä käy kumpaankin ratkaisuksi.

Esimerkkimallia varten kuvataan tilanne, jossa työntekijä on juuri saapunut yrityksen palkkalistoille ja hänelle on määritelty työtehtävä:

Yrityksen uudelle työntekijälle on kuvattu yleiset käytännöt ja yrityksessä yleistyneet tavat (ks. YLEISET KÄYTÄNNÖT). Hän on saanut oman työpisteensä projektin työskentelytiloista (lisää tietoa mallissa TYÖPISTE).

Ongelma

Ongelma on usein suunnittelumallin vaikein osio saada kuntoon. Kokematon kirjoittaja sortuu helposti pohtimaan tai kuvaamaan ratkaisua ja ongelmasta muodostuu ”Miten tehdä <ratkaisu>?”. Toinen helposti tehtävä virhe on takertua ongelman seuraukseen eikä itse juurisyyhyn. Usein törmää myös liian laajaan ongelmakuvaukseen, jonka seurauksena suunnittelumalli sisältää itseasiassa ratkaisuja useampaan ongelmaan. Varsinaisen ongelman löytäminen voi vaatia useita iterointikierroksia, joiden seurauksena ratkaisu voi muuttua ja yksi suunnittelumalli jakautua useaksi tarkemmaksi malliksi.

Jokaiselle projektille on muodostunut oma toimintakulttuurinsa. Uuden työntekijän tullessa projektiin hän ei osaa toimia tämän toimintakulttuurin mukaisesti. Tämä aiheuttaa ylimääräistä stressiä ja vähentää työtehoa.

Voimat

Voimat kuvaavat kontekstissa vaikuttavia, toisinaan keskenään ristiriitaisia, intressejä (esimerkiksi tuotteen lopullinen hinta ja suorituskyky). Suunnittelumallin avulla lukijaa johdatellaan kohti ratkaisua, jossa eri voimat ovat halutussa tasapainossa. Perinteinen tapa selittää suunnittelumallin voimia onkin rinnastaa suunnittelumalli fysiikkaan ja siellä kappaleeseen vaikuttaviin erilaisiin voimavektoreihin. On mahdollista, että samasta lähtötilanteesta samaan ongelmaan on olemassa useita eri ratkaisuja, jolloin tilanteeseen sopivan ratkaisun voi löytää voimien avulla.

Ihminen on sosiaalinen eläin, joka muodostaa erilaisia sosiaalisia yhteisöjä. Yhteisö auttaa tasapainottamaan henkistä kuormaa.

Projektille muodostuu ajan saatossa oma ihmissuhdeverkostonsa, kulttuurinsa, kielensä ja tapansa. Ilman näiden tuntemista työntekijä tuntee itsensä ulkopuoliseksi.

Toimintakulttuuri rakentuu itsekseen ja sen täydellinen, ajantasainen dokumentointi on vaikeaa.

Ratkaisu

Kun lukija on lukenut suunnittelumallin tähän asti, pitäisi kuvatun ratkaisun olla voimien jälkeen ilmiselvä. Lukijan kannalta on helpompaa, jos ratkaisu alkaa yhdellä ytimekkäällä virkkeellä tai kappaleella, joka kuvaa ratkaisun ytimen. Näin lukija saa yleiskuvan suunnittelumallista lukemalla ensin ongelman ja sitten ratkaisun pääkohdan. Jos malli tuntuu sopivalta, lukija saa yksityiskohdat ratkaisusta lukemalla koko mallin. Lyhyttä ongelma-ratkaisu -paria kutsutaan usein myös patletiksi.

Luo wiki-sivusto, jonne kerätään erilaisia yksityiskohtia projektin toimintakulttuurista. Ensimmäisenä tehtävään uusi työntekijä käy tämän wiki-sivuston läpi yhdessä projektipäällikön kanssa.

Jokaisella projektin jäsenellä tulee olla muokkausoikeus sivustoon, jolloin päivittäminen on helppoa. Sisältöä ei pidä rajoittaa liiaksi, mutta liian suuri määrä yksityiskohtia hämärtää kokonaiskuvan. Sivulla voi olla esimerkiksi seuraavia tietoja:

  • Eri projektijäsenten tehtäväalueet projektissa
  • Tiedot ruoka-ajoista ja -paikoista (jos projektilla on tapana käydä yhdessä syömässä)
  • Yhteisiä harrastuksia työajan ulkopuolella
  • IRC ja muut kommunikaatiokanavat

Pelkkä wiki-sivusto harvoin riittää kuvaamaan koko toimintakulttuuria, joten uusi työntekijä sopeutuu paremmin projektiin, kun hänellä on yksi nimetty taho, jolta uuden työntekijän on helppo kysyä toimintakulttuurista ja joka voi kouluttaa työntekijää (katso MENTOR). Tätä suunnittelumallia voidaan käyttää myös koko yrityksen laajuisesti kuvaamaan yritykseen muodostunutta toimintakulttuuria.

Lopuksi

Suunnittelumallien kirjoittamista varten on olemassa muutama hyvä suunnittelumallikieli (kuten A Pattern Language for Pattern Writing ja The Language of Shepherding), joihin kannattaa tutustua. Jos (ja kun) suunnittelumallista tulee tarpeeksi yleiskäyttöinen, sitä voidaan hioa vielä erilaisissa suunnittelumalleihin liittyvissä workshopeissa (PLoP). Eräs kuvaus suunnittelumallien kirjoittamisen iteratiivisesta prosessista löytyy Designing Distributed Control Systems: A Pattern Language Approach -kirjasta.

Suunnittelumallia varten käytetty esimerkki oli tällä kertaa hieman vähemmän tekninen, mutta toisaalta sitäkin yleiskäyttöisempi. Lisäksi Klein ja Weaver ovat tutkineet toimintatapojen oppimisen hyödyllisyyttä ja todenneet sen tärkeäksi.