Dokumentointiohje - Tietokantasovellus

Kurssilla määritellään, suunnitellaan ja toteutetaan pieni www-alustalle toteutettava tietokantajärjestelmä.
Tämä dokumentti antaa suuntaa harjoitustyöltä odotettavasta dokumentaatiosta.
Dokumentissa tulee olla selkeä kappalejako, kansilehti ja sisällysluettelo. Tekstin tulee olla kieliasultaan selkeää.

1. JOHDANTO

2. YLEISKUVA JÄRJESTELMÄSTÄ

Käyttötapauskaavio tai sidosryhmäkaavio

Molemmat kaaviot näyttävät järjestelmän sidosryhmät ja miten ne liittyvät järjestelmään. Tällä kurssilla kehitettävissä järjestelmissä sidosryhminä ovat enimmäkseen järjestelmän käyttäjäryhmät. Muita mahdollisia sidosryhmiä olisi esimerkiksi toiset järjestelmät.

Käyttötapauskaaviossa käyttötapaukset kuvataan järjestelmän sisällä ja sidosryhmien yhteydet järjestelmään esitetään yhteyksinä käyttötapauksiin. Kaavion kuvaa järjestelmästä voisi kuvailla esimerkiksi “Tällaisia asioita järjestelmässä voi tehdä, ja nämä ryhmät tekevät näitä asioita”.

Sidosryhmäkaaviossa sidosryhmien yhteys järjestelmään kuvataan nuolina sidosryhmästä kohti palveluntarjoajaa. Kunkin sidosryhmän karkean tason käyttötapaukset ilmaistaan yhteyden tyyppinä.

Kaavioiden lisäksi käyttäjäryhmät sekä tärkeimmät käyttötapaukset kuvaillaan erikseen myös tekstinä.

Esimerkit

Käyttötapauskaavio

Sidosryhmäkaavio

Käyttäjäryhmät

Annetaan lyhyt kuvaus järjestelmän sidosryhminä toimivista käyttäjäryhmistä.

Esimerkki

Jokamies
    Jokamiehellä tarkoitetaan ketä tahansa, joka Internetin välityksellä tulee lukemaan KatonAlle yhtiön www-sivuja. 
    Kaikki muut sidosryhmät kuuluvat myös tähän sidosryhmään.

Asiakas
    Asiakas on rekisteröitynyt käyttäjä.

Vuokranantaja
    Vuokranantaja on rekisteröitynyt henkilö, joka on antanut asunnon KatonAlle yhtiölle välitettäväksi.

Työntekijä
    Työntekijä on KatonAlle yhtiön palveluksessa oleva henkilö.

Johto
    Johdolla tarkoitetaan työntekijöitä, joiden tehtävänä on tehtävien anto ja asioista päättäminen.

3. KÄYTTÖTAPAUKSET

Käyttötapauksella tarkoitetaan järjestelmän avulla hoidettavaa tavoitteellista tehtäväkokonaisuutta. Esimerkiksi tilauksen kirjaus, tilauksen peruutus ja laskun tulostus ovat tehtäväkokonaisuuksia, joita on luonnollista mallintaa käyttötapauksina. Kustakin käyttötapauksesta kuvataan sen sisältö: mitä käyttötapauksessa tehdään. Raporttien kohdalta kerrotaan, mitä tietoja raporttiin sisältyy.

Käyttötapausten avulla määritellään, mitä järjestelmällä tehdään. Voit luonnostella käyttötapauksia esimerkkitapausten avulla. Esimerkkitapauksessa toiminnan kohde on kiinnitetty. Esimerkiksi ‘ilmoittautuminen Informaatiojärjestelmät kurssin harjoitusryhmään 3’ on esimerkkitapaus käyttötapauksesta ‘luentokurssille ilmoittautuminen’. Voit esittää esimerkkitapauksia myös dokumentissa havainnollistaaksesi käyttötapauksia. Käyttötapaukset voi esittää tärkeysjärjestyksessä, aakkosjärjestyksessä tai käyttäjittäin ryhmiteltyinä.

Esimerkki

Jokamiehen käyttötapaukset

Yritysinfon lukeminen:
    Kuka tahansa voi käydä lukemassa yrityksen mainos- ja yleistietoja 
    mm. työntekijöiden puhelinnumerot ja toimistojen sijainnit.

Asuntotilanteen yleiskuvan selvittäminen:
    Käyttäjälle näytetään, minkä tyyppisiä asuntoja kullakin alueella 
    kyselyn suoritushetkellä on tarjolla vuokralle ja kuinka monta näitä on tarjolla. 
    Esimerkki: Millaisia asuntoja on tarjolla Kruunuhaassa?

Rekisteröityminen asiakkaaksi:
    Rekisteröitymisessä käyttäjä ilmoittautuu yrityksen asiakkaaksi päästen näin 
    yrityksen muiden asiakaspalveluiden käyttäjäksi ja asiakastiedotteiden saajaksi.

    Jokamiehestä tulee asiakas. Hän antaa henkilötietonsa ja saa asiakastunnuksen, 
    joka on avain asiakkaille tarkoitettuihin palveluihin. 

    Prototyypissä asiakastunnus aktivoituu heti. 
    Aktivoinnin voisi kytkeä myös esimerkiksi jäsenmaksun maksamiseen.

4. JÄRJESTELMÄN TIETOSISÄLTÖ

Järjestelmän tietosisältö kuvataan käsitekaavion avulla. Käsitekaavio on järjestelmään säilöttävälle tiedolle käsitetason malli, jonka perusteella johdetaan toteutustason relaatiotietokantakaavio.

Esimerkki

Kaavion lisäksi täytyy kuhunkin tietokohteeseen liittää selitys, jossa määritellään kyseinen kohde. Attribuutit täytyy kuvailla ellei merkitys ole nimen perusteella itsestään selvä. Jos attribuutilla on koodiarvoja tai rajattu arvojoukko, on arvojen merkitys myös selitettävä. Myös yhteydet täytyy määritellä. Alla on esimerkkinä yhden tietokohteen määrittely.

Esimerkki

Tietokohde: Huoneisto
Attribuutti Arvojoukko Kuvailu
Osoite Merkkijono, max. 120 merkkiä Asunnon katuosoite muodossa Paratiisitie 13, Ankkalinna, Calisota, Yhdysvallat
Pinta-ala Desimaaliluku Asunnon pinta-ala neliömetreinä
Hintapyyntö Desimaaliluku Myyjän hintapyyntö euroina.
Huoneisto, joka on annettu myytäväksi, mutta joka ei vielä ole katalogissa voi olla kuulumatta yhdellekään virkailijalle. Kukin huoneisto voi olla kerralla vain yhden virkailijan hoidettavana. Yhdellä virkailijalla voi kuitenkin olla hoidettavanaan useita huoneistoja. Huoneistoon voidaan liittää myös varustelukuvauksia. Huoneistoa koskevista kuvauksista kulloinkin huomioidaan vain viimeisimpänä lisätty. Yksi varustelukuvaus voi kuvata vain yhtä huoneistoa. Huoneiston varustelukuvaus voi olla huoneistoa hoitavan tai jonkun muun virkailijan kirjoittama.

Jos haluat varmistua siitä, että tietosisältömallisi ja käyttötapauksesi sopivat yhteen ja mallit ovat kattavia voit laatia riippuvuusmatriisin kuvaamaan tietokohteiden käsittelyä käyttötapauksissa. Riippuvuusmatriisin sarakkeina ovat kohdetyypit ja yhteydet. Riveinä ovat käyttötapaukset. Kuhunkin sarakkeeseen merkitään, mitä käyttötapauksessa tehdään ko. luokan kohteille (C=create, R=read, D=delete, U=update). Jokaisen käyttötapauksen täytyy käsitellä jotain kohdetta. Tietokohteelle täytyy mahdollistaa riittävät käsittelyoperaatiot käyttötapausten kautta.

5. RELAATIOTIETOKANTAKAAVIO

Relaatiotietokantakaavio esitetään kaaviokuvana ja SQL:n create table lauseina. Kaavioon täytyy sisältyä taulujen välisten viiteyhteyksien ja avainten määritykset. Jos relaatiokaaviossa on attribuutteja, jotka eivät esiinny käsitemallissa tai jonkin käsitemallin attribuutti on karsittu tai sen muotoa on muutettu on tästä erikseen mainittava. Yleissääntönä on, että relaatiotietokantakaavion tulee olla yhteensopiva käsitemallin kanssa.

Create table -lauseet voi antaa liitteenä, jolloin niitä ei tarvitse kirjoittaa dokumentin sekaan.

Alla on esimerkki kaaviokuvasta. Nuolten tulisi lähteä vierasavainten kohdalta, pk = primary key, fk = foreign key.
Huomaa kuitenkin taulun varuste vieras pariavain (huoneisto,laatimisaika) on kuvattu yhdellä nuolella.

Muunnossäännöt käsitemallista relaatiomalliin löytyvät Tietokantojen perusteet kurssin materiaalista.

6. JÄRJESTELMÄN KOMPONENTIT

Kustakin ohjelman komponentista laaditaan erillinen kuvaus, jossa esitetään komponentin ymmärtämisen kannalta oleelliset asiat. Kuvaus on suunnattu henkilölle, joka mahdollisesti joskus joutuisi ylläpitämään ohjelmistoa.

Jokaisen komponentin osalta esitetään sen nimi ja kuvaus siitä, mitä se tekee ts. mikä sen tarkoitus on. Komponentit voidaan esitellä esim. ryhmiteltyinä html-sivuihin, servletteihin ja apuluokkiin. Lisäksi voi omana osionaan luetella sovelluksessa mahdollisesti käytettävät kuva-, ääni- yms. tiedostot. Mikäli sovelluksessa on käytetty jotain kirjastoa, kuten jQuery, tulee eritellä mitkä ovat omia ja mitkä kirjaston komponentteja, käytetyistä kirjastokomponenteista tulee kertoa mihin niitä käyttää.

Esimerkki

index.php
    Sovelluksen etusivu. Sisältää kentät sisäänkirjautumista varten, linkin rekisteröitymissivulle ja lyhyen, 
    mutta kuvailevan kertomuksen järjestelmästä ja sen viimeaikaisesta kehityksestä. Viimeaikaisesta kehityksestä 
    kertovan kentän sisältö täytetään uutissyötteestä dynaamisesti. Sivu tarjoaa myös pikahakukentän, jonka sisältö 
    lähetetään asuntohaku.php:n käsiteltäväksi.

asuntohaku.php
    Tarjoaa hakulomakkeen asuntojen hakua varten ja luettelon hakutuloksista. Hakulomake mahdollistaa hakujen
    tekemisen avainsanan, paikkakunnan ja hintahaarukan perusteella.

resources/dbConnection.php
    Tiedosto, jonka avulla tietokantayhteyden saa avatuksi helposti. 
    Tietokantaa tarvitsevat komponentit käynnistävät tämän tarpeen mukaan.

resources/dbSearchFunctions.php
    Tarjoaa kokoelman funktioita, jotka tekevät tietokantaan kyselyitä ja palauttavat kyselyiden tuloksia eri muodoissa. 
    Tämän kokoelman funktiot keskittyvät erilaisiin asuntotietoihin liittyviin hakuihin ja eivät muuta mitään tietokannassa.

...

resources/header.html
    Jokaisen generoitavan sivun alkuun liitettävä otsaketiedosto, jossa html-sivun yleiset määrittelyt. 
    Asettaa sivujen otsikoksi "KatonAlle Oy" ja kertoo merkistökoodauksen olevan UTF-8.

resources/footer.html
    Jokaisen generoitavan sivun loppuun liitettävä tiedosto. Liittää sivun pohjalle sivun ylläpitäjän sähköpostiosoitteen ja lopettaa sivun.

resources/lib/jokuKirjasto/*
    Käyttämäni kirjaston jokuKirjasto komponentit löytyvät täältä. Seuraavaksi yksilöin sen komponenttien joukosta ne,
    joita olen käyttänyt.

resources/lib/jokuKirjasto/lomakkeentarkastuskomponentti.js
    Olen käyttänyt tätä komponenttia web-lomakkeiden sähköpostikenttien muodon tarkastukseen.

...

Tämän lisäksi ohjelmakoodin tulee olla dokumentoitua (kommentit / javadoc / phpdoc tms.) ja käyttää havainnollisia nimiä muuttujille ja funktioille/metodeille. Ohjelmiston tulee olla jaettuna komponentteihin järkevästi, siten että turhalta toistolta vältytään. Komponentteihin liittyvät yleistiedot on hyvä kirjoittaa myös ohjelmakoodin alkuun yleiskommentiksi, jolloin ne voi vain kerätä ohjelmakoodista dokumenttiin. Ohjelmakoodit sijoitetaan dokumentin liitteiksi.

7. KÄYTTÖLIITTYMÄ

Käyttöliittymän näkymien välisiä yhteyksiä on luontevaa esittää kaavioina. Seuraavassa kuvassa on esimerkki tällaisesta kaaviosta.

Käyttötapausten ja käyttöliittymäkomponenttien välisiä yhteyksiä voi kuvailla tekstimuodossa. Tätä vaatimusta lieventää, jos sivut on nimetty kuvaavasti ja käyttötapauksille tarkoitetut polut rakenteessa ovat intuitiiviset. Sivukohtaisen julkisuusmäärittelyn dokumentoiminen ei ole välttämätöntä, jos esim. asianmukaisen siirtymän kohdalla kertoo, että tästä pääsee eteenpäin vain tunnistettu käyttäjä. Mikäli sivustolla on navigaatiopalkki, jonka johdosta kirjautunut käyttäjä pääsee mistä vain mihin vain, kannattaa tämä mainita sanallisesti kaavion yhteydessä ja merkitä kaavioon vain sellaiset yhteydet, jotka olisivat olemassa ilman navigaatiopalkkiakin.

8. ASENNUSTIEDOT

Asennustietoina kerrotaan, miten järjestelmän tiedostot sijoittuvat hakemistoihin. Kaikki tiedostot voivat olla samassa hakemistossa tai jakautua useaan eri hakemistoon. Ohjeen tarkoituksena on toisaalta kertoa, miten sovellus on nyt asennettu ja toisaalta miten sen saisi asennettua uuteen ympäristöön. Apuluokkien muodostamat pakkaukset pitää esitellä. Servlettien sijoittelu riippuu servlettiympäristöstä, joten sitä ei tarvitse määritellä. Asennusohjeesta tulisi käydä myös ilmi, minne käytettävän tietokannan asetukset (käytettävä tietokanta, käyttäjätunnus, salasana) tulee ohjelmistoa asentaessa määritellä.

9. KÄYNNISTYS- / KÄYTTÖOHJE

Perusoletuksena on, että järjestelmän käyttäjä osaa käsitellä WWW-sivuja selaimella. Tähän liittyviä ohjeita ei siten tarvitse antaa. WWW-sovelluksen tulisi olla helppokäyttöinen ja intuitiivinen. Sivujen pitäisi itsessään sisältää riittävästi sivun käyttöön tarvittavaa informaatiota. Jos sivut ovat tällaisia, riittää antaa ohjelman käynnistykseen tarvittava URL.

Jos käyttöön liittyy joitain yleisiä toimintajärjestykseen liittyviä asioita, ne voidaan kertoa tässä yhteydessä.
Näiden tietojen tulisi löytyä myös tuotettavan järjestelmän sivuilta.

Muista kertoa ohjaajalle mahdolliset testaustunnukset ja salasanat.

10. LIITTEET

Dokumentin liitteinä annetaan: