HY / TKTL / 58160-8 Ohjelmoinnin harjoitustyö / Eräs dokumentointivinkki
Copyright © 1998 Sami Nikander, <niksu@iki.fi>. Tämän oppimateriaalin käyttö on sallittu vain yksityishenkilöille opiskelutarkoituksissa. Materiaalin käyttö muihin tarkoituksiin, kuten kaupallisilla tai muilla kursseilla, on kielletty.
05.03.98

Vinkkejä dokumentointiin

Tämän kuvauksen sisältö:

  1. Mikä on dokumentti?
  2. Miksi ja ketä varten dokumentti tehdään?
  3. Onko ulkoasulla tai kieliasulla väliä?
  4. Missä vaiheessa projektia dokumentti kirjoitetaan?
  5. Dokumentin sisältämät osat ("pakolliset" ja mahdollisesti tarvittavat)
  6. Tehtävänmäärittely ja rajaus
  7. Käyttöohje
  8. Ratkaisumenetelmä ja rajoitukset
  9. Ohjelman (tms.) rakenne
  10. Testaus ja arviointi
  11. Parannusehdotukset ja ylläpito-ohjeet
  12. Liitteet

Mikä on dokumentti?

Ohjelmointityöhön (tai vastaavaan työhön) liittyy yleensä jonkinlainen kirjallinen osuus, työselostus, jossa kerrotaan itse työhön liittyviä seikkoja ja selostetaan myös työn kulkua. Projektin eri työvaiheista saattaa olla omat erilliset kuvauksensa, ja erilaiset työt vaativat erityyppisiä selostuksia. Tätä työn kuvailua eri osineen nimitetään dokumentoinniksi, ja sen tuloksena syntyy dokumentti. Dokumentista halutaan usein paperiversio, jotta sitä olisi helpompi lukea, mutta myös elektronisessa muodossa (esim. WWW-sivuna) oleva dokumentti on yleinen, eivätkä ne ole toisiaan poissulkevia.

Dokumentti ei ole kaunokirjallisuutta eikä kouluaine. Siinä saa (ja on usein suotavaa) käyttää kuvia, taulukoita ja muita apuvälineitä, joilla asia voidaan esittää lukijalle selkeämmin. Kaikkea ei siis tarvitse eikä pidä vääntää sanalliseen muotoon. Dokumentti ei ole proosatekstiä, vaan lähinnä tekninen ja mahdollisimman tarkka ja selkeä kokoelma

Miksi ja ketä varten dokumentti tehdään?

Ohjelmointiprojekti (tai mikä tahansa projekti) on eräänlainen ongelmanratkaisuprosessi: siinä on ongelma tai tehtävä, joka pitää ratkaista, vieläpä niin että ratkaisusta on myöhemminkin iloa jollekulle.

Taloista tehdään rakennuspiirustukset, jotta laajentaminen on myöhemmin mahdollista, ja jotta kukaan ei esim. romauta taloa poistamalla kantavan seinän. Uusista esim. kemian tai fysiikan tutkimuksista tehdään täsmällinen selostus, jotta alan asiantuntijat ymmärtävät, mitä tarkkaan ottaen on tehty, mitä hyötyä keksinnöstä on, mitä puutteita työstä löytyy, ja miten tulokseen on päädytty.

Samoista syistä tehdään myös ohjelmointitöistä dokumentti. Jos et kerro, mitä ja miksi olet tehnyt, mihin olet päätynyt ja miten ohjelmaasi voi käyttää (tehokkaasti), tuskin kukaan vaivautuu sitä ottamaan selville omin päin. Vaikka tekisit ohjelman vain omaksi iloksesi, huomaat muutaman vuoden päästä, että dokumentoimaton ohjelma pöytälaatikossa on lähes mahdoton tulkita jälkikäteen.

Yleisin syy, miksi manuaaleja ei viitsitä lukea kuin äärimmäisessä hädässä, saattaa olla yksinkertaisesti se, ettei niistä yleensä ole apua. Tee sinä toisin ja kirjoita ohjelmallesi selkeä ja tarkka manuaali, josta tiedonhaku on helppoa ja jonka lukeminen on miellyttävää.

Onko ulkoasulla tai kieliasulla väliä?

Dokumentoinnin ulkoinen taso on sekin hyvin tärkeä osoitus sen laadusta. Hyväkin sisältö menee hukkaan, jos sen selvillesaaminen tuottaa lukijalle kohtuutonta vaivaa.

Missä vaiheessa projektia dokumentti kirjoitetaan?

Dokumentin sisältämät osat ("pakolliset" ja mahdollisesti tarvittavat)

Tehtävänmäärittely ja rajaus

Käyttöohje

Ratkaisumenetelmä ja rajoitukset

Ohjelman (tms.) rakenne

Testaus ja arviointi

Parannusehdotukset

Liitteet



<niksu@iki.fi>