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.

---

08.02.99

• Mikä on dokumentti?

  • Ohjelmointityön (tms.) kirjallinen osuus: työselostus, ohjeistus ym.
  • Kerrotaan työhön ja työn kulkuun liittyvät oleelliset seikat
  • Annetaan ohjeita ohjelman käyttäjälle (maallikko)
  • Annetaan ohjeita ohjelman tekniselle ylläpitäjälle (atk-ammattilainen)
  • Ei ole kouluaine eikä kaunokirjallisuutta, vaan tekninen kuvaus, jossa pyritään asian tarkkuuteen ja selkeyteen
  • Kuvia, taulukoita, kaavioita ym. apuvälineitä jopa suotavaa käyttää
  • Paperiversio: helppo lukea ja kommentoida; WWW: helppo päivittää

• Miksi ja ketä varten dokumentti tehdään?

  • Ohjelmointiprojekti on ongelmanratkaisua
  • Pyörää ei kannata keksiä uudestaan:
    Vrt. talojen rakennuspiirustukset, tieteellisten tutkimusten raportit
  • Kun olet ratkaissut tehtävän, ratkaisu pitää yleensä kyetä selittämään muille tai uudelleenkäyttämään myöhemmin jossain muualla
  • Mitä ja miksi olet tehnyt?
  • Mihin tulokseen päädyit?
  • Miten ohjelmaasi voi käyttää (tehokkaasti)?

• Onko ulkoasulla tai kieliasulla väliä?

  • Hyväkin sisältö menee hukkaan, jos sen selvillesaaminen tuottaa lukijalle kohtuutonta vaivaa
  • Hienot fontit ja nelivärikuvat eivät ole pääasia, vaan helppolukuinen ulkoasu, josta on nopeaa kaivaa tieto esille
  • Tökerö kielenkäyttö ärsyttää usein lukijaa
  • Oikoluvun teettäminen kaverilla kannattaa aina: omille virheilleen tulee sokeaksi lukiessaan samaa tekstiä sadatta kertaa
  • Muiden arviot auttavat myös sisällön parantamisessa

• Missä vaiheessa projektia dokumentti kirjoitetaan?

  • Dokumentti kirjoitetaan työn ohella: aina kun työ edistyy, siitä kirjoitetaan saman tien uusi osio dokumenttiin
  • Asioiden muistelu jälkikäteen ei onnistu
  • Kirjoittaminen helpompaa pieninä palasina, yhteen aihekokonaisuuteen kerrallaan liittyen
  • Myös parantelu ja korjailu helpompaa, jos kirjoittaa ensimmäisen version ajoissa

• Mitä dokumentissa on pakko olla? Mitä ei saa olla?

  • Kansilehti: Työn nimi, dokumentin tyyppi, kirjoittaja, pvm, paikka, oppilaitos etc.
  • Sivunumerointi (alkaa yleensä vasta sisällysluettelon jälkeen numerosta 1)
  • Mahdollisesti tiivistelmä, jossa hyvin lyhyt kuvaus dokumentin sisällöstä ja aihepiiristä (omalle sivulleen)
  • Sisällysluettelo: omalle sivulleen, otsikot ja alaotsikot, viittaukset sivunumeroihin
  • Numeroidut otsikot ja alaotsikot, ei kuitenkaan "3.6.4.5.2.2"-tarkkuudella asti
  • Otsikoiden korostaminen tekstistä (lihavointi, isompi fontti...)
  • Kuville ja taulukoille kuvanumerot ja mielellään myös kuvatekstit
  • Mahdolliset liitteet eri sivunumeroinnilla tai ilman numerointia

• Käyttöohje

  • Suunnattu loppukäyttäjälle, jolla vain minimaalinen atk-osaaminen
  • Ei atk-teknisiä termejä (itse sovellusalueen slangi sallittu)
  • Ei varsinkaan viittauksia toteutukseen ("on tällainen luokka"...)
  • Ohjelman asennus/käyttöönotto, käynnistys, käyttö, lopetus ja ylläpito
  • Kaikki toiminnot, tunnetut virheet ja ongelmatilanteet kuvattava

• Tekninen dokumentti

  • Ongelman lyhyt kuvaus (= määrittelydokumentin asiat)
  • Ratkaisumenetelmä ja valitun ratkaisun asettamat rajoitukset
  • Ulkoiset rajoitukset: laitteisto- ym. rajoitukset
  • Ohjelman tietorakenteet ja algoritmit
  • Ohjelman ajonaikainen toiminta
  • Testiraportti: tekeekö ohjelma mitä se on ohjelmoitu tekemään?
  • Ylläpitoon vaikuttavat asiat, laajennettavuus ja parannusehdotukset

• Post mortem -analyysi

  • Yleensä osana ohjelmointiprojekteja
  • Oma arvio projektin kulusta ja onnistumisesta
  • Raportti: tekeekö ohjelma mitä sen alunperin haluttiin tekevän? Onko ohjelma vastaus juuri siihen kysymykseen, joka esitettiin, vai meneekö se "huti"?