Sovellusraportin ensimmaisesta versiosta huomioita.

Kirjoittajan mukaan: Jukka-Pekka Santanen <jukka-pekka.santanen_at_mit.jyu.fi_at_localhost>
Päiväyksen mukaan: Wed, 16 May 2012 17:08:09 +0300
Terve!

Sovellusraportti on sisällöltään melkoisen mallikas ensimmäiseksi
versioksi, joten ohjaan palautteen ryhmän jäsenten ohella myös
tilaajan edustajille ja tekniselle ohjaajalle. Jari kävi reilu 
tunti sitten poimimassa paperikappaleeseen kirjaamani tarkemman 
palautteeni.

Puutteiden osalta täydennetyn seuraavan version voisi lähettää 
koko projektiorganisaation arvioitavaksi. Hyväksyykö muuten 
Tero Kallioinen tilaajan edustajista sovellusraportin, jos hän 
jatkokehittää sovellusta projektin jälkeen? Minun ohella myös 
tekninen ohjaaja Outa Valkama on luvannut tarkastaa raportin
tietotekniikan laitoksen osalta.

Laajimmat sisällölliset puutteet ovat mielestäni seuraavat:
  - Projektissa kehitetyn tietojärjestelmän taustoja tulee 
    kuvata joko johdannossa tai luvussa 7.1 omassa alaluvussaan.
    Sopivat tekstikappaleet löytynevät projektiraportista.
  - Käyttöliittymän kuvia uupuu etenkin tutkijan käyttöliittymästä. 
  - Vapaaehtoisia harjoitteita ei käsitellä missään luvun 3
    alaluvuista, mutta luvussa 4 niitä käsitellään.
  - Luvusta 4 uupuu näkymän ''Edistyminen'' kuvaus tai sitä ei
    mainita luvun 4.8 jatkokehitykseen sovituissa ominaisuuksissa.
  - Sovelluksen rakennetta ja toteutusratkaisuja kuvaava luku 
    kaipaa täydentämistä. Pari sen alalukua on kokonaan tyhjiä
  - Luvut 5.2 ja 5.3 ovat tyhjiä. Niissä riittää siis kuvata
    sovellusta yleisellä tasolla ja viitata luokkien ja metodien
    tarkemman kuvauksen osalta luokkadokumentteihin. Ideana on
    siis, että lukija saa yleiskäsityksen tietojärjestelmästä 
    sekä sen sisältämistä sovelluksista ja komponenteista.
    Luokkiin ja metodeihin pääsee paremmin käsiksi, kun ymmärtää
    yleisrakenteen ja laajemmat toteutusratkaisut.
  - Tietokannalle kannattaa varata oma päälukunsa, jossa on
    ER-kaavio ensimmäisessä alaluvussa ja kukin taulu kuvataan
    omassa alaluvussaan. Kunkin taulun tarkoituksen ohella tulee 
    kuvata lyhyesti kunkin kentän tarkoitus ja tyyppi (vaikkapa
    luvun 2 termilistojen tapaan). Ainakin hankalimmin 
    ymmärrettävien taulujen käyttöä kannattaa havainnollistaa
    lyhyillä riviesimerkeillä.
  - Luvun 5.5 nykyisen sisältö ei kuvaa toteutusratkaisujen
    kehittymistä, vaan sovelluksen kehittymisen etenemistä.
    Sen tekstikappaleet kannattaa siirtää projektiraportin
    prosessia kuvaavaan alalukuun. Luvussa 5.5 tulee kuvata
    olennaisimmat toteutusratkaisuissa tehdyt muutokset ja
    syyt niille.
  - Luvusta 6 uupuu testausten tulosten kuvauksen alaluku. 
    Havaittiinko testauksessa joitain toistuvia virheitä ja 
    puutteita sekä miten ne korjattiin? Jäikö sovellukseen 
    joitain testauksessa havaittuja virheitä ja puutteita.
    Jos havaitut virheet ja puutteet kuvataan jo jossain
    toisessa alaluvussa, niin riittää vain mainita ne sekä
    viittata lukunumerolla kyseiseen alalukuun. (Samaa asiaa
    ei siis kannata toistaa eri alaluvuissa tai kappaleissa.)
  - Tunnettuja puutteita ja virheitä sekä jatkokehitysideoita 
    kuvaavat luvut kaipaavat myös täydentämistä. 
  - Jatkokehittäjien (ja ylläpitäjien, ei tutkijoiden) ohjeita 
    kuvaavaan lukuun kannattaa lisätä ainakin kaksi alalukua. 
    Niissä voisi mielestäni käsitellä tietokokonaisuuden (ts.
    puuttuvien hallittavien kohteiden) hallintanäkymän lisäämistä 
    ja tehtäväkomponenttien lisäämistä. Mahdollisten muidenkin
    puuttuvien tai virheellisten toimintakokonaisuuksen lisäämistä
    sovelluksiin olisi jotenkin hyvä ainakin yleisesti ohjeistaa 
    jatkokehittäjille, että he pääsevät ainakin ''osittain 
    katettuun pöytään''.

Pienempiä olennaisia lähinnä yksittäisiin alalukuihin tai
tekstikappaleisiin liittyviä huomioitani ovat seuraavat:
  - Lukuja 1 ja 2 koskeva palautteeni kannattaa vilkaista
    projektiraportin eilisestä palautteestani.
  - Lukujen 3 ja 4 otsikoissa rooli kannattaa siirtää suluista
    ensimmäisiksi sanoiksi.
  - Luvut 3 ja 4 kaipaavat johdantoonsa parin virkkeen yhteenvetoa. 
    Niissä voisi mainita ainakin toimintakokonaisuudet, joiden
    toteuttaminen sovittiin tilaajan kanssa jatkokehitykseen.
  - Sisäänkirjautumisnäkymiin tulisi ottaa lyhyesti kantaa
    luvuissa 3.1 ja 4.1. Ehkäpä niille ei kuitenkaan kannata
    varata omaa alalukua.
  - Luvuissa 3.1 ja 4.1 toistetaan kuvien asiat listoissa. 
    Kyseisiä listoja kannattaa täydentää kuvaamalla ainakin
    muutamalla sanalla ko. toimintakokonaisuuksien tarkoitusta 
    ja/tai toimintoja.
  - Luvuissa 3 ja 4 käytetään sekaisin käsitteitä aikataulut ja 
    kuntoutusohjelmat. Kyseiset käsitteet tulee ainakin sitoa 
    yhteen, mutta mielestäni kuntoutusohjelma olisi kuvaavampi
    (käytettäväksi myös käyttöliittymässä, jatkokehitysidea?).
  - Miten luvun 5.1 kaksi viimeistä tekstikappaletta liittyvät
    asiakas-palvelinarkkitehtuuriin? Eikö luvussa tulisi kuvata
    MVC-mallin toteutusratkaisua lyhyesti.
  - Luvun 6 sisältö vaikuttaa samalta kuin projektiraportissa,
    joten siihen kirjaamani huomiot kannattaa käydä läpi.
    Saisiko luvun 6 sisältöä ainakin osittain tarkennettua
    projektiraportin yleiseen kuvaukseen verrattuna?
  - Mäntylän Meerin palautteesta on mainittava luvussa 6.5.
    Kyseisessä alaluvussa tulee myös viitata Meerin, minun ja
    Tero Kallioisen palautteisiin, jotka tulee kirjata 
    erillisiksi lähteiksi lähdeluetteloon.
  - Luvussa 7.1 kannattaa mainita vaatimusten tilat jätetyn
    tietoisesti korkeintaan toteutetuiksi. Tilan ''testattu''
    käyttö vaatisi suunnitelmallista ja hallittua sovellusten
    järjestelmätestausta.
  - Salasanojen tallennuksesta salattuun muotoon tulee mainita
    luvussa 7.2 tai 7.3. Luvussa 7.3 kannattanee viitata
    joihinkin aiempiin alalukuihin, jottei tarvitse toistaa 
    aiemmissa luvuissa käsiteltyjä kehitysideoita.
  - Yhteenvedossa tulee ottaa kantaa siihen, soveltuuko 
    projektissa toteutettu sovellus tuotantokäyttöön, rajattuun
    tuotantokäyttöön vai antaako protytyyppi (hyvän) pohjan
    tuotantoversion kehittämiselle.
  - Yhteenvedossa kannattaa myös parilla virkkeellä tiivistää
    toimintakokonaisuudet, jotka toteutuivat ja/tai eivät 
    toteutuneet. Mahdolliset olennaisimmat virheet ja puutteet
    voi olla myös järkevä mainita.
  - Tuloksia tai sovelluksen toimintoja ei koskaan ''jätetä
    toteuttamatta'', vaan niiden siirtämisestä projektin 
    jälkeiseen jatkokehitykseen sovitaan aina tilaajan kanssa.

Ensimmäistä kertaa esiintyviä olennaisia käsitteitä kannattaa
lihavoida. Kyseisten ''kappaleotsikoiden'' avulla lukija saa 
nopeasti yleiskäsityksen tekstikappaleisen sisällöstä ja löytää
etsimänsä. Esimerkiksi lukujen 3 ja 4 käyttöliittymien osien
käyttötarkoituksia kannattaa lihavoida ja/tai näkymien
tekstejä kursivoida.

Luku- ja kuvaviittaukset luku- ja kuvanumeroilla uupuvat vielä.
Lähdeluettelon kaikkiin lähteisiin ei viitata. Lähdeluettelosta
uupunee vielä ainakin sovelluksen kehityksen yhteydessä käytetyt
olennaisimmat kirjat ja verkkolähteet. Meeri Mäntylän, minun ja
Tero Kallioisen palautteet tulee kirjata erillisiksi lähteiksi 
lähdeluetteloon.

Teksti on mukavan sujuvaa, mutta kirjasin muutamiin kohtiin
ehdotuksia paremman esitystavan tai sanavalinnan osalta.
Kirjoitusasukin on pääosin mallikas, sillä havaitsin vain
yksittäisiä pieniä kirjoitusvirheitä.

Olen torstaista sunnuntaihin Jyväskylän ja verkkoyhteyksien
ulkopuolella. Käyn loppuviikosta kuitenkin läpi päivitetyn 
vaatimusmäärittelyn ja kuntoutettavan sovelluksen koodeista 
generoidut luokkadokumentit. Saan ryhmälle niistä palautteen
maanantaina.

Terveisin,
              jukka-pekka


-- 
#  Jukka-Pekka Santanen (PhD, Mr)    #  santanen_at_mit.jyu.fi
#  Department of Mathematical        #  http://www.mit.jyu.fi/santanen/
#  Information Technology            #
#  University of Jyvaskyla           #  Room: Agora AgC418.2
#  P.O. Box 35 (Agora)               #  Phone: +358- (0)40 8053299
#  FIN-40014 University of Jyvaskyla #  
Received on 16.05.12 17:08:09

Tämän arkiston loi hypermail 2.2.0 : 16.05.12 17:08:11 EEST