Hei ahkerat labralaiseni!

Tässä hieman lisää osviittaa, mitä haluan suunnitteludokumenttiin.  Luen
ja kommentoin sekä käyttöohjeen että suunnitteludokun, eli saatte ne
mahdollisimman pian punakynämerkinnöin varustettuina takaisin
itsellenne.  Näin voitte ottaa korjausehdotukset huomioon lopullista
versiota miettiessänne.  Samaten kommentoin skenaarioiden ja
luokkasuunnitelmien tms. kohtien mahdollisia puutteita, joten niitäkin
ehdotuksia ehtii vielä ottaa huomioon koodatessa. 

Dokumenteissa on kansilehti, sisällysluettelo, numeroidut otsikot
sekä sivunumerointi. Haluan dokumentit paperilla, en tiedostoina.
Työtänne helpottaa siis, jos käytätte jotain "oikeata"
tekstinkäsittelyohjelmaa, esim. Wordia, WordPerfectia,
tai Unixissa vaikkapa LaTeXia. HTML on näppärä tapa tehdä www-sivuja,
mutta www-sivujen printtaus on teille aika työläs tapa tuottaa
dokumentti...

Työtänne helpottaa myös, jos käytätte jotain jo osaamaanne työkalua,
ettei aikaa kulu teksturin opetteluun. Minulta saa toki pikaohjeen
esim. Wordiin (sisällysluetteloiden yms. tekoon) ja LaTeXiin.

Seuraavassa teknisen dokumentin sekä käyttöohjeen sisältöhahmotelmaa. 
Huomioikaa, että otsikoiden ei yleensä tarvitse (eikä joskus edes
tulisi) olla juuri tuonnimisiä! Tuo on vain asiasisältö, jaottelun
ja nimeämisen saa kukin keksiä itse!

Jos tulee kiire dokumenttien deadlinen kanssa (tai muidenkin
aikarajojen), ilmoitelkaa AJOISSA, että ette pysty saamaan hommaa
kasaan määräajassa. Jos lipsutte ilmoittamatta, kenkää tulee varsin
herkästi - eli merkkaan keskeyttäneeksi, jollei mitään kuulu ja
välietappeja ei täytetä. Tarvittaessa joustan deadlineissa kunhan
otatte yhteyttä ajoissa, eikä vasta viimeisenä päivänä!


		SUUNNITTELUDOKUMENTTI
		---------------------

Suunnitteludokumenttiin pitäisi tulla selostukset seuraavista asioista:

* ongelman kuvaus
	- samaa asiaa kuin "asiakkaalle" annetussa
	  tehtävänrajauksessakin, mutta tässä kirjoitettu 
	  "atk-ammattilaisen näkökulmasta"
	- käytännössä useimmiten sama teksti kuin olette jo
	  kirjoittaneet määrittelydokumenttiin
	- voi sisältää kuitenkin enemmän eksakteja määritelmiä,
	  esimerkkiaineistoa ym. kuin alkuperäinen tehtävänrajaus

* ohjelman rakenne ja toimintalogiikka
	- luokkakaavio / Pascal-ohjelmissa aliohjelmiin jako
	- skenaariot, metodien kutsukaavio / Pascalissa esim. pseudokoodi

* luokkien ja metodien tarkempi kuvaus
	- joka luokasta kerrotaan sen tarkoitus, muuttujat ja metodit,
	  tärkeimmät metodit myös selostettuna tarkemmin
	- tärkeätä on kertoa joka luokasta riittävän kattavasti,
	  mikä luokan tehtävä ja tarkoitus on
	- myös jokaisesta tärkeästä aliohjelmasta selostus: 
	  parametrit, paluuarvo, tarkoitus ja toiminta 
	  (esim. pseudokoodina)
	- hoituu myös ohjelmoinnin ohessa JavaDoc-ohjelmalla, 
	  JOS kommentoitte koodinne niin hyvin, että kommenteissa on em.
	  asiat esitettynä!

* ohjelman ratkaisuidea
	- mitä algoritmeja tms. ratkaisumalleja ohjelma käyttää,
	  miten ohjelma ratkaisee sen, mitä ikinä se tekeekään, siis
	  miten ohjelma vastaa annettuun ongelmaan
	- ratkaisumenetelmän dokumentointia: miten päädyttiin juuri tähän
	  luokkaratkaisuun (joo, usein vastaus taitaa olla "ohjaaja ehdotti" ;)

* ratkaisun rajoitukset 
	- mitä etuja ja rajoituksia tehdyillä suunnitteluratkaisuilla on?
	  (esim: "taulukkototeutus on ongelma, jos haluttaisiin muuttaa
	  kortiston kokoa", "tämä järjestysalgoritmi toimii hyvin myös 
	  suurilla järjestettävien määrillä"...)
	- onko kielellä tai toteutusympäristöllä jotain lisärajoitteita?

* tietorakenteiden kuvaus 
	- missä tietoja säilytetään ajon aikana (taulukot, listat...),
	  entä minkämuotoisissa tiedostoissa ajojen välillä jne. Myös 
	  valitut valmiit "työkalut" hyvä mainita, esim. jos käyttää 
	  java.util.Hashtablea tms.
			
* käyttöliittymän kuvaus
	- selostus ohjelman vuorovaikutuksesta käyttäjän kanssa:
	  miten käyttäjä juttelee ohjelman kanssa, mitä
	  dialogeja/komponentteja/näyttöjä/toimintoja jne. ohjelmassa on,
	  esim. piirros selityksineen


Lopulliseen tekniseen dokumenttiin tulevat em. asiat korjauksineen
*plus* seuraavat:

* testiraportti
	- miten ohjelman toimivuudesta on varmistuttu?
	- siis mitä asioita testattu ja miten (millä syötteillä)?
	- pyritään korjaamaan virheet, ei dokumentoimaan niitä
	  => jos virhe löytyy, se korjataan ja tehdään testiajo
	  uudelleen, kunnes kaikki testit menevät läpi virheettä.
	- jos ei jää aikaa korjata virheitä, ei voi muuta kuin 
	  dokumentoida virheen ja arvion sen syystä ja korjaustavasta
	- parempi kuitenkin että itse huomaa virheen ja dokumentoi sen,
	  kuin että ohjaaja löytää ne ennen opiskelijaa...!

* lähdekoodi

* eroavaisuudet suunnitelman ja todellisuuden (=toteutuksen) välillä
  (vaihtoehtoisesti suunnitteludokumentin korjaaminen niin, että
   se vastaa syntynyttä lopputulosta)

		KÄYTTÖOHJE
		----------

Käyttohjeessa puolestaan on suunnilleen seuraavat osat:
(Osa näistä selviää vasta kun ohjelma on valmis, osan olisi taas hyvä
olla selvillä jo ennen koodausta! Ne, mitä ei vielä tiedä, voi jättää
pois toistaiseksi)

* Ohjelman tarkoitus 
	- taas suunnilleen samaa asiaa, kuin tehtävänrajauksessa:
	  mitä ohjelma osaa tehdä ja mitä ominaisuuksia siinä yleisesti
	  ottaen on
	- tällä kertaa näkökulmana kuitenkin on peruskäyttäjä

* Vaatimukset ohjelman käyttämiselle ja asennusohjeet
	- millainen kone ja ohjelmistot tarvitaan ohjelman ajamiseen?
	- mitä tiedostoja kokonaisuuteen kuuluu?
	- miten ohjelma asennetaan ja miten se käynnistyy?

* Termien selitykset ja käytetyt merkinnät
	- jos ohjelmassa on käytetty jotain "ei yleisesti tunnettuja"
	  tai erikoisia merkintätapoja tai termejä, ne olisi hyvä selostaa

* Toiminnan kuvaus 
	- jaoteltuna joko esim. yhden session/pelierän/tyypillisen
	  käyttötilanteen sujumisen mukaan, tai toimintojen loogisen
	  jaottelun mukaa
	- ohjeessa käsiteltävä KAIKKI tilanteet, joihin käyttäjä voi
	  ohjelmaa käyttäessään joutua, sekä kuvattava KAIKKI toiminnot,
	  joita ohjelmasta löytyy
	- myös virhetilanteet (esim. mitä tapahtuu väärä syöte
	  annettaessa) ja niistä toipuminen selostettava, nehän
	  ovat myös tilanteita, joihin käyttäjä voi ajautua!

* Ohjelman mahdolliset virheet (bugit)
	- jos ohjelmaan jää virheitä, vähintä mitä voi tehdä on 
	  kertoa niiden olemassaolosta myös käyttäjälle!

* Tekijän tiedot
	- lisätietojen kysymistä ja bugiraportteja varten
	

-- 
-------------+ 100 little bugs in the code, 
PROGRAMMER'S | 100 little bugs in the code, fix one bug, compile it again.
 DRINKING    | 101 little bugs in the code, 
___SONG______| 101 little bugs in the code... Repeat until BUGS = 0