Vaatimusmäärittelydokumentti

Vaatimusmäärittelydokumentti Mooan Helsinki 08.06.2006 Ohjelmistotuotantoprojekti HELSINGIN YLIOPISTO Tietojenkäsittelytieteen laitos

Kurssi 581260 Ohjelmistotuotantoprojekti (9+1op/6ov) Projektiryhmä Heikki Aitakangas Mika Holmström Kirsi Jokisalo Anni Kotilainen Esko Lehtonen Paula Urpilainen Ohjaaja Ilari Moilanen Asiakas Sami Palhomaa Johtoryhmä Juha Taina Kotisivu http://www.cs.helsinki.fi/group/mooan/ Versiohistoria Versio Päiväys Muokkaaja Kuvaus 1.0 24.5.2006 Lehtonen Ensimmäinen luonnos pe 19.5. kokouksen sekä aikaisemman Anno-projektin pohjalta 1.1 26.5.2006 Lehtonen Muokattu 26.5. kokouksen perusteella. Tehty paremmin annotointityökalun todellista käyttöä vastaavia käyttötapauksia. 1.2 30.5.2006 Lehtonen 30.5.2006 kokouksessa käsiteltyjen asioiden pohjalta muokattu 1.3 1.6.2006 Lehtonen Muokattu 1.6. kokouksen ja asiakkaalta saadun palautteen pohjalta. 1.4 8.6.2006 Lehtonen, Urpilainen Muokattu 5.6. ja 8.6. pidetyn kokouksen perusteella asiakkaalle hyväksyttäväksi. 1.5 16.6.2006 Lehtonen Asiakkaalta saadun palautteen ja kälidemon pohjalta muokattu. 1.6 18.7.2006 Urpilainen Termien yhtenäistäminen suunnitteludokumentin kanssa

Sisällysluettelo 1.Johdanto...1 2.Sanasto...1 3.Käyttäjävaatimukset...2 4.Käyttötapaukset...9 4.1.Käyttötapaus I. Raportin tuottaminen ryhmässä...10 4.2.Käyttötapaus II. Kommenttien kerääminen omaan tekstiin...10 4.3.Käyttötapaus III. Tekstin muokkaaminen palautteen perusteella...10 4.4.Kuinka käyttötapaus III toteutettaisiin järjestelmässä?...10 5.Käyttöskenaariot...11 5.1.Kommenttien selailu...12 5.2.Dokumentin selailu kommenttia luettaessa...13 5.3.Uusien kommenttien selailu...13 5.4.Kommentin lisääminen...14 5.5.Viestin kirjoitus, eli kommentin kommentointi...14 5.6.Kommentin poistaminen...15 5.7.Kommentin valitseminen päällekkäisistä kommenteista...16 5.8.Kommentoidun tekstin muokkaaminen...16 5.9.Kommentointiominaisuuden kytkeminen päälle/pois dokumenttikohtaisesti...17 5.10.Dokumentin tulostaminen...17 5.11.Kaikkien dokumenttiin liittyvien kommenttien selailu...18 6.Järjestelmäarkkitehtuuri...18 7.Järjestelmävaatimukset...19 8.Järjestelmämallit...20 9.Ympäristövaatimukset...21 10.Tuotteen elinkaari...21

1.Johdanto Mooan-ohjelmistotuotantoprojektin tarkoituksena on tuottaa kommentointi- eli annotointityökalu Moodle-oppimisalustalle. Työkalua on tarkoitus käyttää ensisijaisesti yhteisöllisessä kirjoittamisessa kommenttien ja palautteen antamisen apuvälineenä. Verrattuna keskustelupalstaan tai sähköpostilistaan annotointityökalun etuna on se, että kommentit saadaan liitetyksi suoraan kontekstiin eli oikeaan paikkaan dokumentissa. Vaatimusdokumentissa kuvataan ohjelmistolle asetetut vaatimukset. Vaatimukset jakautuvat käyttäjä-, järjestelmä-, ja ympäristövaatimuksiin. Käyttäjävaatimukset kuvaavat, mitä järjestelmällä pitää voida tehdä. Järjestelmävaatimukset kuvaavat kuinka nämä tulee teknisellä tasolla toteuttaa. Ympäristövaatimukset kuvaavat ympäristön, jossa järjestelmän tulee toimia ja johon ei voida projektin puitteissa vaikuttaa. Vaatimusten lisäksi käsitellään mitä järjestelmän elinkaaresta tiedetään. Vaatimusdokumenttia lukiessa voidaan havaita, että käyttäjävaatimuksia on huomattavasti enemmän ja ne ovat myös yksityiskohtaisempia kuin järjestelmä- tai ympäristövaatimukset. Tähän on syynä ohjelmiston luonne. Annotointityökalu on interaktiivinen ohjelmisto, jota on oltava hyvä käyttää. Käytettävyys on tärkeää, koska ainoastaan siten annotointityökalu voi tarjota jotain keskustelupalstaa tai sähköpostia parempaa kommenttien ja palautteen annon välineenä. Suoranaisten vaatimusten lisäksi järjestelmässä kuvataan käyttötapauksia, jotka valottavat järjestelmän suhdetta todellisiin käyttötilanteisiin. Lisäksi käydään läpi käyttöskenaarioita, joissa käydään läpi järjestelmän toiminnallisuutta. Näiden erottamista toisistaan helpottaa se, että ajattelee käyttötapausten kuvaavan sitä, mitä käyttäjät haluavat tehdä järjestelmästä riippumatta, ja käyttöskenaarioiden sitä, mitä he järjestelmän kanssa tekevät. Järjestelmävaatimusten kontekstin hahmottamiseksi kuvataan järjestelmän arkkitehtuuri sekä järjestelmän sisältämän informaation rakennetta. Yksityiskohtaisempi järjestelmän kuvaus jätetään kuitenkin suunnitteludokumenttiin, koska järjestelmän sisäisen toiminnallisuuden suhteen ei ole tarkkoja ennakkovaatimuksia. Vaatimusdokumentti on muokattu yhdessä asiakkaan kanssa. Asiakas myös viimekädessä hyväksyy vaatimusdokumentin. Näin vaatimusdokumentti toimii myös sopimuksena asiakkaan ja ohjelmistotuotantoprojektin kesken siitä, minkälaista ohjelmistoa ryhdytään toteuttamaan. Tämän vaatimusdokumentin inspiraationa on käytetty aikaisemman Annoohjelmistotuotantoprojektin vaatimusdokumenttia. Sisältö on kuitenkin mietitty täysin uusiksi yhdessä asiakkaan kanssa. 2.Sanasto Annotointi Luokitellun kommentin lisääminen. Dokumentti HTML-, XML, teksti- tai Wiki-sivu Moodle-oppimisalustalla. Kommentti Dokumenttiin tehty huomautus tai lisämerkintä. Järjestelmä Ellei kontekstista muuta ilmene: projektin puitteissa toteutettava kommentointityökalu kokonaisuutena. Tähän ei lueta Moodlea. 1

Kommenttikategoria Kommentin luokka, esim. oikeinkirjoitus- tai sisältökommentti Keskustelu Kommentin viestit. Muokkausnäkymä Näkymä, josta voi lukea ja kirjoittaa kommentteja sekä viestejä. Kommenttinäkymä Näkymä, jossa voi lukea kommentteja ja keskusteluja Opasteikkuna Pieni ikkuna dokumentin ylälaidassa, joka kertoo annotointiominaisuudesta ja mahdollistaa sen päälle- ja poiskytkemisen. Viesti Kommentin kommentti tai vastaus sellaiseen. Muodostavat hierarkkisen puurakenteen kommentin ympärille. 3.Käyttäjävaatimukset Käyttäjävaatimukset on luokiteltu ja numeroitu. Numerointi on muotoa x.y. Tässä x ilmaisee käyttäjävaatimuksen aihekokonaisuuden ja y varsinaisen käyttäjävaatimuksen. Käyttäjävaatimuksiin on lisätty myös perustelu, jonka tarkoituksena on helpottaa ymmärtämään miksi käyttäjävaatimus on esitetty, sekä myös tarvittaessa rohkaisee tarkastelemaan käyttäjävaatimusta kriittisesti. Järjestelmävaatimukset on priorisoitu 1-3, missä 1 tarkoittaa välttämättä toteutettavaa vaatimusta, 2 vaatimusta josta voidaan karsia jos aikataulu pettää, ja 3 vaatimusta jonka toteuttamiseen ryhdytään vasta jos aikaa jää yli. 1 Ydintoiminnallisuus 1.1 Tekstimuotoisiin dokumentteihin voi lisätä tekstimuotoisia kommentteja. Perustelu: Tekstistä voidaan keskustella, mikä on hyödyllistä kirjoitettaessa tekstejä yhdessä. Luokitus: Toiminnallinen 1.2 Kommentit lisätään suoraan kontekstiin. Perustelu: Helpottaa kommentoitavan tekstin ja kommenttien välisen suhteen hahmottamista. 1.3 Kommenteista voi käydä keskustelua. Perustelu: Kommenteista täytyy pystyä esittämään kysymyksiä ja niihin pystyy vastaamaan. Luokitus: Toiminnallinen 1.4 Kommentteja sekä niistä käytävää keskustelua voivat lukea kaikki, joilla on lukuoikeus dokumenttiin. Perustelu: Työvälinettä on tarkoitus käyttää ennen kaikkea yhteisöllisen oppimisen tukemiseen. Luokitus: Toiminnallinen 2

2 Käyttöoikeudet 2.1 Annotointiominaisuus on oletuksena kytketty pois päältä. Jos annotointiominaisuus on pois päältä, uusia kommentteja tai viestejä ei voi kirjoittaa. Perustelu: Annotointi voidaan rajata vain joihinkin dokumentteihin tai dokumenttien versioihin. 2.2 Käyttäjä, jolla on Moodlessa sivun muokkausoikeudet, voi kytkeä annotointiominaisuuden päälle sivukohtaisesti. Perustelu: Muokkausoikeuksilla varustettu käyttäjä voi muuttaa sivun sisältöä ja kommentit voi nähdä dokumentin interaktiivisena sisältönä. 2.3 Vierailijakäyttäjä voi lukea kommentteja ja kommenttien viestejä sivuilta, joihin hänellä on Moodlessa lukuoikeus, mutta ei pysty kirjoittamaan omia. Perustelu: Sisältö on avointa jos dokumenttikin, tällä tavalla voidaan rajata tehokkaasti asiattomia tai asianvierestä olevia kommentteja pois. 2.4 Rekisteröityneellä tunnuksella Moodleen kirjautunut voi lukea ja kirjoittaa kommentteja ja kommenttien viestejä sivuilla, joihin hänellä on lukuoikeus ja joiden annotointiominaisuus on kytketty päälle. Perustelu: Rekisteröityneet käyttäjät tuntevat vastuunsa asiallisesta käyttäytymisestä, joten heitä ei tarvitse erikseen rajoittaa. 3 Kommentin esittäminen dokumentissa 3.1 Dokumentin kommentit ovat merkityt siihen kohtaan, mihin kommentti liittyy. Perustelu: Käyttäjän on helppo havaita dokumentin kommentit ja se mihin kohtaan tekstiä ne liittyvät. 3.2 Kommentin merkitsemiseen käytetään tekstin korostusta tai alleviivausta. Korostettu ja alleviivattu alue on samalla dokumentin kohta, johon kommentti on liitetty. Perustelu: Korostus tai alleviivaus ei tee muutoksia itse dokumentin sijoitteluun tai rakenteeseen. 3.3 Kommentti liittyy aina yhteen katkeamattomaan tekstipätkään. Perustelu: Pidetään asiat yksinkertaisena. 3

3.4 Kommentit voivat olla päällekkäisiä. Perustelu: Toinen kommentti voi koskea koko kappaleen sisältöä ja toinen kappaleen yksittäisen sanan kirjoitusasua. 3.5 Käyttäjä erottaa kommentin merkintätavan perusteella mihin kategoriaan kommentti kuuluu. Perustelu: Käyttäjä pystyy keskittymään erikseen esimerkiksi sisällöllisiin ja kielellisiin kommentteihin. 3.6 Käyttäjä erottaa kommentin merkintätavan perusteella onko hän jo lukenut kommentin. Perustelu: Käyttäjä pystyy keskittymään itselleen uusiin kommentteihin. Prioriteetti: 2 3.7 Käyttäjä erottaa kommentin merkintätavan perusteella onko kommenttiin tullut uusia viestejä kommentin viimeisen avaamisen jälkeen. Perustelu: Käyttäjä pystyy paremmin seuraamaan kommenteista käytävää keskustelua. Prioriteetti: 2 Huomio kohtiin 2.2-4: Visualisointi on tärkeää, koska suodatusominaisuudet priorisoidaan matalalle tasolle. 4 Kommenttinäkymä eli kommentin sisällön esittäminen 4.1 Vietäessä hiiri dokumenttiin merkityn kommentin päälle, näytetään tooltip-tyylisessä kommenttinäkymässä kommentti ja kommenttiin liittyvä keskustelu. Perustelu: Kommentteja voi tällä tavalla pikaselata. 4.2 Vietäessä hiiri pois kommentin tai kommenttinäkymän päältä kommenttinäkymä poistuu ilman erillistä sulkemista. Perustelu: Tarvitaan vähemmän turhia näpäytyksiä. 4.3 Kommenttinäkymä avataan kommentin viereen, samalla tavalla kuin tyypilliset tooltipikkunat. Perustelu: Kommentti on helppo lukea tekstin paikkaa kadottamatta. 4.4 Kaikki viestit sisältöineen näkyvät samassa ikkunassa kommentin kanssa. Perustelu: Vältetään turhaa navigointia. 4

Tarkennus: Voidaan käyttää ylös-alas -vierityspalkkia, koska näin säästetään näyttötilaa. Ylös-alas vierittäminen käyttäjäystävällisempää kuin sivuttaisvierittäminen. 4.5 Keskustelun puurakenteen visualisointiin käytetään mahdollisimman pientä sisennystä. Perustelu: Kommenttinäkymä ei saa olla niin iso, että se haittaisi dokumentin lukemista. 4.6 Kommenttinäkymästä voi avata yhdellä näpäytyksellä muokkausnäkymän. Perustelu: Muokkausnäkymään tulee päästä helposti, mutta se voi kuitenkin olla näpäytyksen takana. 4.7 Muokkausnäkymästä voi lukea kommentin ja keskustelun kuten kommenttinäkymäistäkin. Lisäksi siinä tarjotaan tilanteen mukaan kommentin ja viestin kirjoitus, muokkaus ja poisto-ominaisuudet. Perustelu: Muokkausnäkymää käytetään lukemista harvemmin tehtäviin toimintoihin. 4.8 Kommentista näytetään kommenttiteksti, kirjoittaja ja aika. Perustelu: Kaikki ovat olennaisia tietoja. 4.9 Viestit, joita käyttäjä ei ole aikaisemmin lukenut tai ei ole avannut kommenttia ko. viestien kanssa, näkyvät keskustelussa uusina. Perustelu: Helpottaa uusien viestien löytämistä keskustelusta. Prioriteetti: 2 5

Kaavio 1: Kommenttinäkymä Tämä on alkuperäinen kommenttiteksti. Tähän tulee vastauksena viestejä, jotka on järjestetty puuhierarkian mukaan. Tässä on ensimmäinen viesti kommenttiin. Tässä ensimmäinen vastaus ensimmäiseen viestiin. Tässä on toinen viesti kommenttiin. 5 Kommenttien tekeminen 5.1 Dokumentissa, jota voi annotoida, on pieni opasteikkuna sivun ylälaidassa, jossa kerrotaan kuinka kommentteja tehdään. Samassa ikkunassa on linkki laajempaan helpsivuun. Perustelu: Annotointikäyttöliittymä on tällöin mahdollisimman vähän tiellä, mutta tarjoaa käyttäjälle kuitenkin tiedon ominaisuudesta. Luokitus: Toiminnallinen 5.2 Käyttäjät, joilla on siihen oikeus, voivat kytkeä annotointiominaisuuden päälle ja pois opasteikkunan säätimestä. Säädin myös visualisoi onko ominaisuus päällä vai pois. Perustelu: Säätömahdollisuus on dokumentin yhteydessä ja säädön status on aina helposti selvitettävissä. Luokitus: Toiminnallinen 5.3 Kommentin lisääminen tapahtuu maalaamalla kommentoitava kohta hiirellä, ja valitsemalla kommentin lisäämistoiminnon valikosta, joka tulee esiin maalauksen jälkeen maalatun kohdan viereen. Perustelu: Hiiri on helpoin tapa valita tekstialue, jota kommentoidaan. 5.4 Kategorian valinta tapahtuu valikossa, joka avautuu kommentin lisäämistoiminnon valitsemista varten. Perustelu: Tämä sen takia, että käyttäjät tiedostaisivat jo ennen kommenttia, mistä asioista heidän aikovat kirjoittaa. Tämä voi pitää kommentit selkeämpinä. 6

6 Kommenttien ja viestien poisto 6.1 Kommentteja ja viestejä voi poistaa kunnes niitä on kommentoitu. Perustelu: Kirjoittamisen jälkeen saattaa ymmärtää asian uudella tavalla ja tulla katumapäälle. Keskustelurakenteen koossa pitämiseksi vastattuja kommentteja tai viestejä ei voi poistaa. 6.2 Ylläpitäjä tai sivun opettajakäyttäjä voi poistaa kirjoituksia aina. Kommenteista tai viesteistä, joihin on vastauksia, poistetaan samalla kaikki vastaukset. Perustelu: Ylläpitäjän ja opettajan täytyy pystyä poistamaan mahdollisia asiattomuuksia tai ilmeisiä virheitä. 7 Kirjoitusten muokkaus 7.1 Kirjoituksia voi muokata, kunnes niihin on vastattu. Perustelu: Kieli- ja ajatusvirheitä saattaa havaita juuri julkaisemisen jälkeen. Prioriteetti: 2 7.2 Ylläpitäjä tai sivun opettajakäyttäjä voi muokata kirjoituksia aina. Perustelu: Ylläpitäjän tai opettajan täytyy pystyä poistamaan mahdollisia asiattomuuksia tai ilmeisiä virheitä. Prioriteetti: 3. On olemassa jo poisto-ominaisuus, jota käytettäneen ensisijaisesti. 8 Muokkausnäkymä 8.1 Muokkausnäkymä avautuu aina ruudun alalaitaan dokumentin ikkunasta erilliseen frame-kaltaiseen ikkunaan. Perustelu: Ruudun alalaidassa ikkuna mataloittaa dokumentin esittämiseen käytettävissä olevaa tilaa. Käyttäjä voi kuitenkin ratkaista tämän ongelman dokumentin ylös-alas -vierittämisellä. Tämä on parempi kuin näyttötilaa kaventavat ratkaisut, joissa dokumentin rivitystä voisi joutua muuttamaan, tai dokumentin päälle aukeavat ikkunat, joita täytyy yleensä raahata eri paikkoihin. Käyttäjä myös oppii ensimmäisen käyttökokemuksen myötä mihin ikkuna avautuu, joten järjestelmä toimii ennakoitavasti. Frame-kaltaisen ratkaisun etuna esimerkiksi päällä olevaan popup -ikkunaan on se, että myös dokumentin loppuosa on aina luettavissa. Luokitus: Toiminnallinen Tarkennus: Muokkausnäkymän sisältöä voi vierittää, jos sisältö ei mahdu näytölle. 8.2 Muokkausnäkymässä on sama sisältö ja toiminnot, kuin kommenttinäkymässäkin, mutta lisäksi siinä on tekstikenttä johon voi kirjoittaa uuden kommentin tai viestin, sekä tarvittaessa kommentin tai viestin muokkaus- ja poistotoiminnot. Perustelu: Pidemmälle menevät ominaisuudet sijoitetaan muokkausnäkymään. 7

Luokitus: Toiminnallinen 8.3 Muokkausnäkymä sulkeutuu a) jos käyttäjä sulkee sen. Perustelu: Käyttäjä voi rauhassa lukea ja pohtia dokumenttia lukiessaan kommentteja tai kirjoittaessaan uutta, kun ei käytetä aikakatkaisua. Muokkausnäkymästä täytyy kuitenkin tarvittaessa päästä pois. b) jos käyttäjä on kirjoittanut uuden kommentin ja tallentaa sen. Perustelu: Uuden kommentin kirjoittamisen jälkeen käyttäjä tuskin ensimmäiseksi haluaa muokata tai poistaa sen, tai kirjoittaa siihen vastausta. c) kun käyttäjä siirtyy toiselle sivulle. Perustelu: Kommentin ovat sivukohtaisia. Jos käyttäjä haluaa selailla muita dokumentteja kirjoittaessaan dokumenttia, hän voi käyttää eri selainikkunaa. 8.4 Jos käyttäjä klikkaa muokkausnäkymän auki ollessa toista kommenttia, latautuu tämä kommentti muokkausnäkymään. Perustelu: Muokkausnäkymiä on järkevä sijoittaa näytölle vain yksi. Käyttäjältä ei pidä vaatia muokkausnäkymän erillistä sulkemista. 8.5 Muokkausnäkymän tallentamattoman kommentin häviämisestä varoitetaan käyttäjää. Perustelu: Käyttäjä voi tehdä virhenäpäytyksiä tai hän voi kuvitella voivansa palata edelliseen muokkausnäkymään selaimen Takaisin-painikkeella. 9 Tulostaminen 9.1 Kommentteja on voitava tulostaa yhdessä dokumentin kanssa. Perustelu: Halutaan tulostaa esimerkiksi kommenttien arvostelua varten. 9.2 Kommentit on numeroitu dokumenttiin tekstialueen kohdalle ja tulosteen lopussa ovat kommentit ja viesteineen. Kommenttien ja keskustelun visualisointi samoin kuin kommenttinäkymässä. Perustelu: Käytetään yhtenäistä, selkeää ja helposti toteutettavaa ratkaisua. 10 Dokumentit ja versiot 10.1 Kommentit ovat dokumentti- ja versiokohtaisia. 8

Perustelu: Käydään keskustelua vain kyseisestä dokumentista ja pidetään asiat yksinkertaisina. 10.2 Niiden dokumentin kohtien kommentit, joita ei ole muokattu, siirretään versiosta toiseen. Perustelu: Pienet muutokset eivät poista kaikki kommentteja. Prioriteetti: 2 Huomio: Jos toteutetaan, korvaa kohdan 10.1. 10.3 Muokattujen kohtien kommentit voi siirtää halutessaan uuteen versioon. Perustelu: Esimerkiksi päällekkäisten kommenttien kohdalla tämä on toivottavaa. Prioriteetti: 3. Toteuttaminen todennäköisesti teknisesti ja käyttöliittymän kannalta hyvin monimutkaista. Huomio: Jos toteutetaan, korvaa kohdat 10.1-2. 11 Muita 11.1 Kommenttikategorioita on oltava ainakin oikeinkirjoitus- ja sisältökommentti. Perustelu: Sisältöön ja muotoon on usein helpompi keskittyä erikseen. 11.2 Kommentteja on voitava suodattaa dokumentista, eli pitää pystyä valitsemaan mitkä kommentit näkyvät. Suodattaminen on oltava mahdollista ainakin kirjoittajan, kirjoitusajan ja viestin vastaavien ominaisuuksien sekä kommentin kategorian perusteella. Perustelu: Käyttäjä voi selkeyttää dokumentin ulkoasua poistamalla vähemmän relevantit kommentit näkyvistä. Prioriteetti: 3. Ominaisuus ei kriittinen järjestelmän toiminnan kannalta. Lisäksi kommenttien visualisointiominaisuudet toteuttavat suurimman osan näistä tarpeista. 11.3 Kaikkia dokumentin kommentteja ja niihin liittyvää keskustelua voi tarkastella puurakenteena visualisoituna erillisestä ikkunasta. Perustelu: Tämä ominaisuus on hyödyllinen, jos kommentteja käytetään esimerkiksi arvostelun perusteena. Prioriteetti: 3. Kaikkia kommentteja ja niihin liittyvää keskustelua voi tarkastella tulostusnäkymästäkin. 4.Käyttötapaukset Käyttötapausten kautta koetetaan ymmärtää käyttäjän ja käyttöympäristön järjestelmälle asettamia vaatimuksia. Käyttötapauksissa nostetaan esiin käyttäjien tavoitteet ja tarpeet. Näin pystytään 9

paremmin arvioimaan, mitkä toiminnot ovat järjestelmän kannalta keskeisimpiä. Tämä auttaa osaltaan priorisoimaan vaatimuksia vaatimusmäärittelyvaiheessa, sekä suunnittelun ja toteutuksen edetessä. 4.1.Käyttötapaus I. Raportin tuottaminen ryhmässä Oppilaitoksessa on käynnissä kurssi, joka pohjautuu yhteisölliseen tiedonrakenteluun. Kurssin osallistujat on jaettu ryhmiin. Kukin ryhmä tuottaa omasta aiheestaan dokumentin prosessikirjoittamisen metodilla. Käytännössä ryhmä siis kirjoittaa yhteisöllisesti dokumenttia Moodlen Wikissä. Wikissä kaikki voivat muokata toisten kirjoittamia tekstejä tai kommentoida niitä järjestelmän avulla. Ryhmä luonnostelee esiversion dokumentista, jonka se julkaisee muiden ryhmien kommentoitavaksi kerätäkseen palautetta ja ideoita. Myös opettaja osallistuu palautteen ja ideoiden antoon. Palautteen ja ideoiden keräämisen jälkeen ryhmä muokkaa annetun palautteen perusteella dokumentia wikissä tarkoituksenaan tuottaa uusi versio dokumentista. Näin jatketaan kunnes dokumentista on saatu lopullinen versio. Lopulliseen versioon kerätään vielä palaute muiden ryhmien jäseniltä sekä opettajalta. 4.2.Käyttötapaus II. Kommenttien kerääminen omaan tekstiin Alfred kirjoittaa artikkelia mustikoiden käytöstä ruuanlaitossa. Hän saa esiversion tehtyä ja asettaa siitä html-sivun, esille. Hän pyytää kokkaus-postituslistan jäseniä arvostelemaan sitä käyttämällä annotointijärjestelmää. Viikon kuluttua Alfred jatkaa artikkelin työstämistä ja saatuaan lopullisen version valmiiksi, lähettää sen postituslistalle. Hän laittaa myös kopion verkkoon, jotta muut voisivat kommentoida sitä helposti annotointien avulla. 4.3.Käyttötapaus III. Tekstin muokkaaminen palautteen perusteella Käyttäjä Alfred kommentoi käyttäjän Bertil kirjoittamaa tietokoneiden virransäästöominaisuuksia käsittelevää tekstiä Wikiin. Kommentissa hän kysyy Bertililtä kannattaisiko asiaa tarkastella myös taloudellisesta näkökulmasta ympäristönäkökulman lisäksi. Bertil haluaa vielä varmistaa tarkoittiko Alfred kansantaloudellista vai yksityisekonomista näkökulmaa. Alfred vastaa, että yksityisekonomista. Bertil etsii aiheesta lisätietoja ja muokkaa tekstiään. 4.4.Kuinka käyttötapaus III toteutettaisiin järjestelmässä? Käyttötapaus 3 on sen verran rajattu, että voidaan koettaa hahmotella, kuinka käyttötapaus toteutettaisiin järjestelmän toiminnallisuuden puitteissa. 1 Bertil julkaisee dokumentin 2 Alfred lukee Bertilin dokumentin 3 Alfred tekee kommentin Bertilin dokumenttiin 10

3.1 maalaa hiirellä kommentoitavan kohdan 3.2 lisää kommentin 3.2.1 kirjoittaa kommenttitekstin 3.2.2 julkaisee kommenttitekstin 3.2.3 palaute kommentin lisäämisen onnistumisesta... 4 Bertil avaa dokumentin 5 Dokumenttia selatessaan Bertil havaitsee uuden kommentin, joka vaikuttaa kiinnostavalta, koska se on hänen kirjoittamassa tekstissä 6 Bertil lukee kommentin... 7 Bertil haluaa kysyä lisätietoja Alfredilta 7.1 kirjoittaa tarkentavan kysymyksen 7.2 palaute kommentin viestin lisäämisen onnistumisesta... 8 Dokumenttia selatessaan Alfred havaitsee, että kommenttiin on tullut viesti 8.1 Alfred avaa kommentin ja lukee uudet viestit 8.2 Alfred vastaa kommenttiin 8.2.1 kirjoittaa vastauksen tekstikenttää 8.2.2 julkaisee viestin 8.2.3 palaute viestin lisäämisen onnistumisesta 8.2.3.1 Alfred näkee vastauksen... 9 Dokumenttia selatessaan Bertil havaitsee, että kommenttiin on tullut viesti 9.1 Bertil avaa kommentin ja lukee uudet kommentit... 10 Bertil muokkaa wiki-tekstiä uudenlaiseksi 11 Alfredin kommentti on vanhentunut, koska sen esittämät muutokset on jo tehty 11.1 Alfredin kommentti häviää 5.Käyttöskenaariot Käyttöskenaarioissa tarkastellaan järjestelmän toimintoja. Skenaarioissa kuvataan järjestelmän alkutila, normaalitapahtumakulku ja järjestelmän lopputila, johon normaalin tapahtumakulun kautta päädytään. Lisäksi kuvataan ennakoitujen poikkeustilanteiden käsittely sekä järjestelmän samanaikainen toiminta, mikä on käyttäjälle näkymättömissä. 11

Kaavio 2: Käyttöskenaariokaavio 5.1.Kommenttien selailu Alkutila Tapahtumakulku Dokumentti on auki selaimessa ja kommentit näkyvät korostettuina tekstissä. Käyttäjä vie hiiren kiinnostavan kommentin päälle, jolloin sen viereen avautuu kommenttinäkymä. Jos koko kommentti ja siihen liittyvä keskustelu eivät mahdu näkymään kerralla, ilmestyy myös vierityspalkki, jonka avulla käyttäjä voi selailla kommenttinäkymää. Tutustuttuaan kommenttiin, käyttäjä vie hiiren pois kommentin ja kommenttinäkymän päältä, jolloin kommenttinäkymä häviää. 12

Poikkeustilanteet Mitä muuta tapahtuu Systeemin tila lopuksi 1) Kommentti on poistettu dokumentin latauksen ja kommentin avaamiskomennon välisenä aikana: Ei mahdollista, koska kommentit sisältöineen aina dokumentin latauksen yhteydessä. Järjestelmä tallettaa tiedon siitä, että käyttäjä on lukenut kommentin ja kommentin viestit. Sama kuin alkutilassa. 5.2.Dokumentin selailu kommenttia luettaessa Alkutila Tapahtumakulku Poikkeustilanteet - Mitä muuta tapahtuu Systeemin tila lopuksi Dokumentti on auki selaimessa ja kommentit näkyvät korostettuina tekstissä. Käyttäjä vie hiiren kommentin päälle, jolloin sen viereen avautuu kommenttinäkymä. Käyttäjä näpäyttää kommenttinäkymästä muokkausnäkymän auki. Kommenttinäkymä häviää ja käyttäjä voi selailla sekä dokumenttia että nyt muokkausnäkymässä näkyvää kommenttia ja siihen liittyvää keskustelua yhtä aikaa. Kun käyttäjä ei enää tarvitse kommenttia, hän sulkee muokkausnäkymän. Järjestelmä tallettaa tiedon siitä, että käyttäjä on lukenut kommentin ja kommentin viestit. Sama kuin alkutilassa. 5.3.Uusien kommenttien selailu Alkutila Tapahtumakulku Poikkeustilanteet - Mitä muuta tapahtuu Systeemin tila lopuksi Dokumentti on auki selaimessa ja kommentit näkyvät korostettuina tekstissä. Kommenttien merkintätavasta näkyy, ovatko ne uusia tai onko niihin liittyvään keskusteluun lisätty uusia viestejä. Käyttäjä selaa dokumenttia kunnes hän löytää kommentin, jonka korostuksesta näkyy että se on uusi tai että siihen liittyvässä keskustelussa on uusia viestejä. Käyttäjä tutustuu kommenttiin samoin kuin käyttöskenaariossa Kommenttien selailu, hän löytää uudet viestit niiden korostuksen perusteella. Järjestelmä tallettaa tiedon siitä, että käyttäjä on lukenut kommentin ja kommentin viestit. Sama kuin alkutilassa. 13

5.4.Kommentin lisääminen Alkutila Tapahtumakulku Poikkeukset Dokumentti on auki selaimessa ja kommentit näkyvät korostettuina tekstissä. Käyttäjä maalaa hiirellä dokumentista tekstialueen, jota hän haluaa kommentoida. Sen jälkeen hän valitsee kommentointitoiminnon ja sen, koskeeko kommentti tekstin sisältöä vai oikeinkirjoitusta. Sivun alalaitaan ilmestyy muokkausnäkymän, jonka sisältämään tekstikenttään käyttäjä kirjoittaa kommenttinsa. Hän voi vapaasti selailla dokumenttia kommenttia kirjoittaessaan. Kun kommentti on valmis, käyttäjä valitsee Tallenna ja muokkausnäkymä sulkeutuu. 1) Dokumentin annotointia ei ole kytketty päälle tai käyttäjällä ei ole oikeutta lisätä dokumenttiin kommentteja: Annotointitoiminto ei ole aktiivinen. 2) Käyttäjän maalaama teksti ei kuulu dokumentin sisältöön, se on esim. osa käyttöliittymää: Annotointitoiminnon valitsemisesta ei seuraa mitään. Mitä muuta tapahtuu Systeemin lopputila 3) Dokumentti on poistettu tai tapahtuu muu tietokanta- tai palvelinvirhe: Käyttäjälle näytetään informatiivinen virheilmoitus. Tallentamisen yhteydessä järjestelmä koodaa kommentin paikan dokumentissa ja siirtää tämän tiedon kommentin yhteydessä tietokantaan. Kirjataan muistiin myös käyttäjän tunnus ja kommentinlisäysaika. Sama kuin alkutilassa, sillä lisäyksellä että myös uusi kommentti näkyy korostettuna. 5.5.Viestin kirjoitus, eli kommentin kommentointi Alkutila Tapahtumakulku Dokumentti on auki selaimessa ja kommentit näkyvät korostettuina tekstissä. Käyttäjä avaa muokkausnäkymän sille kommentille, jota hän haluaa kommentoida tai johon liittyvään keskusteluun tuo kommentti kuuluu viemällä hiiren kommentin päälle ja näpäyttämällä avautuvaa kommenttinäkymä. Avautuvassa muokkausnäkymässä kommentti on korostettu vastattavaksi, mutta käyttäjä voi valita minkä tahansa viesteistä vastattavaksi, jolloin se vaihtuu korostetuksi. 14

Poikkeukset Muokkausnäkymässä käyttäjä valitsee kommentin (tai viestin) aktiiviseksi (ellei se jo ole), ja kirjoittaa viestinsä tekstikenttään. Tämän jälkeen hän valitsee tallenna. 1) Käyttäjä ei haluakaan tallentaa kommenttia: Hän sulkee ikkunan. 2) Käyttäjä näpäyttää toisen kommentin auki muokkausnäkymään: Ennen kommentin avaamista käyttäjältä kysytään haluaako hän ensin tallentaa viestin. 3) Käyttäjällä ei ole oikeutta lisätä viestejä: Kommenttinäkymän klikkaamisesta ei tapahdu mitään muokkausnäkymä ei ilmesty. Mitä muuta tapahtuu Systeemin lopputila 4) Dokumentti tai kommentoitava kommentti on poistettu, tai tapahtuu muu tietokanta- tai palvelinvirhe: Käyttäjälle näytetään informatiivinen virheilmoitus. Uusi viesti lisätään tietokantaan. Sama kuin alkutilassa, 5.6.Kommentin poistaminen Alkutila Tapahtumakulku Dokumentti on auki selaimessa ja kommentit näkyvät korostettuina tekstissä. Käyttäjä avaa muokkausnäkymän sille kommentille, jonka hän haluaa poistaa tai johon liittyvään keskusteluun tuo kommentti kuuluu viemällä hiiren sen päälle ja näpäyttämällä avautuvaa kommenttinäkymää. Muokkausnäkymässä niiden kommenttien kohdalla, jotka käyttäjällä on oikeus poistaa, näkyy poistotoiminto. Käyttäjä valitsee hiirellä poistotoiminnon sen kommentin kohdalta, jonka hän haluaa poistaa. Käyttäjältä pyydetään vahvistus poistosta virheiden välttämiseksi. Jos hän vahvistaa poiston, kommentti poistetaan ja se häviää dokumentista ja muokkausnäkymästä. Poikkeustilanteet Mitä tapahtuu Muokkausnäkymä jää auki, kun käyttäjä ei enää tarvitse sitä hän sulkee sen. 1) Kommentti on jo poistettu: Sama tulos kuin jos käyttäjä olisi itse poistanut kommentin. 2) Dokumentti on poistettu tai tapahtuu muu tietokanta- tai palvelinvirhe: Käyttäjälle näytetään informatiivinen virheilmoitus. Kommentti poistuu tietokannasta. Tietokannasta poistetaan myös kommenttiin kirjoitetut viestit. 15

Lopputila Sama kuin alkutilassa, paitsi että dokumentista puuttuu poistettu kommentti. 5.7.Kommentin valitseminen päällekkäisistä kommenteista Alkutila Tapahtumakulku Dokumentti on auki selaimessa ja kommentit näkyvät korostettuina tekstissä. Käyttäjä vie hiiren sellaisen kohdan päälle, johon liittyy useita kommentteja. Näkyviin tulee alku jokaisesta kohtaan kuuluvasta kommentista, joiden päälle käyttäjä vie hiiren. Poikkeustilanteet - Mitä muuta tapahtuu - Lopputila Käyttäjän siirtäessä hiirtä esiin tulee sen kommentin kommenttinäkymä, jonka alun päällä hiiri on. Näin käyttäjä valitsee haluamansa kommentin. Samoin kuin alkutilassa, sillä lisäyksellä että valitun kommentin kommenttinäkymä on avattuna. 5.8.Kommentoidun tekstin muokkaaminen Alkutila Tapahtumakulku Poikkeustilanteet - Mitä muuta tapahtuu Lopputila Dokumentti on auki selaimessa. Käyttäjä muokkaa dokumenttia kohdasta johon liittyy kommentteja. Järjestelmä poistaa muokattuun alueeseen liittyvät kommentit tietokannasta. Samoin kuin alkutilassa, paitsi että kommentit ovat hävinneet muokatusta kohdasta. 16

5.9.Kommentointiominaisuuden kytkeminen päälle/pois dokumenttikohtaisesti Alkutila Tapahtumakulku Poikkeustilanteet Mitä muuta tapahtuu Lopputila Dokumentti on auki selaimessa. Käyttäjä valitsee painikkeen kytkeäkseen dokumentista annotointiominaisuuden päälle tai pois. Käyttäjälle annetaan palaute siitä, onko toiminto päällä vai pois. 1) Käyttäjällä ei ole kirjoitusoikeuksia dokumenttiin: Annotointiominaisuuden päälle/pois kytkemisominaisuus ei ole näkyvissä. 2) Dokumentti on poistettu tai tapahtuu muu tietokanta- tai palvelinvirhe: Käyttäjälle näytetään informatiivinen virheilmoitus. Järjestelmä tallentaa tiedon siitä, voiko dokumenttia kommentoida.. Sama kuin alkutilassa. 5.10.Dokumentin tulostaminen Alkutila Tapahtumakulku Dokumentti on auki selaimessa. Käyttäjä valitsee Tulosta kommentein -toiminnon. Käyttäjälle avataan tulostuskelpoinen selainikkuna, jossa kommentit on merkitty tekstiin korostettuina. Kommentit keskusteluineen näkyvät puurakenteena dokumentin jäljessä. Korostetut kohdat on liitetty kommenttiteksteihin numeroinnilla. Poikkeustilanteet Tämän jälkeen tulostaminen tapahtuu selaimen tulostustoiminnon kautta. 1) Dokumentti poistettu ja sitä yritetään ladata uudestaan tulostamista varten: Annetaan virheilmoitus. Mitä muuta tapahtuu - Lopputila 2) Kommentti tai viesti poistettu, ja niitä yritetään ladata uudestaan tulostamista varten: Tulostetaan dokumentti olemassa olevin kommentein ja viestein. Dokumentti auki ja käyttäjällä tulostusvalmiina selainikkuna, jossa näkyvillä: Dokumentti Kommenttien paikat merkattu ja niissä viitenumero 1, 2.... 1. Kommenttiteksti Kommentin viestit lineaarisesti aikajärjestyksessä 2. Kommenttiteksti Kommentin viestit lineaarisesti aikajärjestyksessä. 17

5.11.Kaikkien dokumenttiin liittyvien kommenttien selailu Alkutila Tapahtumakulku Poikkeustilanteet Mitä muuta tapahtuu - Lopputila Dokumentti on auki selaimessa. Käyttäjä valitsee kaikkien kommentit -toiminnon. 1) Dokumentti on poistettu tai tapahtuu muu tietokanta- tai palvelinvirhe: Käyttäjälle näytetään informatiivinen virheilmoitus. Käyttäjälle näytetään uudella sivulla kaikki dokumenttiin liittyvät kommentit keskusteluineen. 6.Järjestelmäarkkitehtuuri Mooan-annotointityökalua käytetään Moodle-oppimisalustan osana. Käyttäjälle järjestelmä näkyy www-selaimen kautta. Järjestelmän käyttöliittymä toteutetaan käyttäjän selaimessa ajettavalla ohjelmalla, joka muokkaa tarvittaessa näytettävää dokumenttia dynaamisesti. Selain on tietoliikenneyhteydessä Internetin yli palvelimella sijaitsevaan Moodleen, jonka yhtenä moduulina toteutetaan osa Mooanin toiminnallisuudesta. Mooan-moduuli käyttää myös Moodlesta ja järjestelmästä erillistä Annotea-palvelinta kommenttien tallentamiseen. Kokonaisuudessaan järjestelmän arkkitehtuuri on luonteeltaan asiakas-palvelin -tyylinen. Kaavio 3: Järjestelmäarkkitehtuuri 18

7.Järjestelmävaatimukset Järjestelmävaatimukset kuvaavat järjestelmälle asetettavia teknisiä vaatimuksia. Ne eivät kuvaa kuinka järjestelmä toteutetaan, vaan pikemminkin toteutuksen teknisiä rajoituksia. Järjestelmävaatimukset on priorisoitu 1-3, missä 1 tarkoittaa välttämättä toteutettavaa vaatimusta, 2 vaatimusta, josta voidaan karsia, jos aikataulu pettää, ja 3 vaatimusta, jonka toteuttamiseen ryhdytään vasta, jos aikaa jää yli. 1. Käyttäjät autentikoidaan Moodlen kautta. Järjestelmä tarkistaa jokaisen käyttäjäryhmältään rajoitetun toiminnon (esimerkiksi kommentin lisääminen, kts. kohta käyttöoikeudet) kohdalla, että asiakasohjelma (selain) asianmukaisesti autentikoinut itsensä Moodlen kautta. 2. Kommentit ladataan käyttäjän selaimelle dokumentin lataamisen yhteydessä. Perustelu: Kommenttien lataaminen vasta tarvittaessa voi tuoda tietoliikenneyhteyksistä johtuvia viiveitä, mikä tekisi käyttöliittymästä liian hitaan. 3. Tuettavia dokumenttityyppejä, joita voi kommentoida, ovat HTML, XHTML, teksti ja Moodlen Wiki-dokumentit. Perustelu: Näitä käytetään Moodlen kursseilla. 4. Kommentit keskusteluineen ja dokumentit on talletettava toisistaan erikseen eli kommentointi ei saa muuttaa dokumentteja. Perustelu: Dokumentti ja kommentit keskusteluineen ovat eri asiakokonaisuuksia. Dokumenttia voidaan haluta käyttää kommenteista riippumatta. 5. Kommenttien siirtämiseen järjestelmien välillä käytetään W3C:n Annotea-rajapintaa. Perustelu: Standardisoituihin rajapintoihin tukeutuminen parantaa ylläpidettävyyttä. 6. Tietokantayhteydet tehdään Moodlen tietokantarajapinnan kautta. Perustelu: Standardisoituihin rajapintoihin tukeutuminen parantaa ylläpidettävyyttä. 7. Kommenttikategoriat nimineen ja ulkoasuineen on pystyttävä konfiguroimaan asennusvaiheessa. Perustelu: Kategorioiden tarve voi vaihdella käytön mukaan. Prioriteetti: 2 19

8. Järjestelmä integroidaan Moodleen olemassa olevan plugin-rajapinnan kautta. Perustelu: Tällä tavalla järjestelmästä saadaan ylläpidettävämpi ja se kestää paremmin Moodlen muutoksia. Prioriteetti: 2. Tästä voidaan joutua tinkimään, koska järjestelmän toteutettavuus Moodlepluginina on jossain määrin avoin kysymys. Moodlen teknisestä puolesta ei ole kovin paljoa dokumentaatiota eivätkä resurssit ole riittäneet vielä tässä vaiheessa lähdekoodin perusteelliseen tutkimiseen. 9. Kommenttikategoriat nimineen ja ulkoasuineen on pystyttävä konfiguroimaan käyttöliittymän kautta käytön aikana. Perustelu: Kategorioiden tarve voi vaihdella käytön mukaan. Prioriteetti: 3. Tämä ei ole järjestelmän käytön tai toiminnan kannalta olennainen ominaisuus. Toteuttaminen lisää myös huomattavasti työnmäärä. 8.Järjestelmämallit Järjestelmä on Internetissä toimiva informaatiojärjestelmä eli se tallettaa, pitää yllä ja esittää käyttäjien siihen tuottamaa informaatiota. Tällaisen järjestelmän kannalta on olennaista tunnistaa mitä informaatiota käyttäjät järjestelmään tuottavat ja mitä he haluavat siitä ulos. Toiseksi on olennaista selvittää informaation ontologia, eli mitä käsitteitä käytetään. Kaavio 4: Informaation tuottajat ja kuluttajat. Nuoli kuvaa informaation suuntaa. Rekisteröitynyt käyttäjä Opettaja Kommentti Viesti Vieras Semanttinen datamalli kuvaa informaation ontologian, eli millaista dataa järjestelmässä käytetään. Lisäksi se kuvaa datan välisiä yhteyksiä. Mallissa keskitytään loogiseen rakenteeseen, ei implementaatioon. Esimerkiksi mallissa mainittu Dokumentti koostunee Moodlen tiedostomuotoisesta dokumentista sekä järjestelmän erilliseen tietokantaan tallennetuista attribuuteista. 20

Kaavio 5: Semanttinen datamalli 9.Ympäristövaatimukset Ympäristövaatimukset kuvaavat mihin järjestelmän on sopeuduttava. Ympäristövaatimuksia ei voi priorisoida, koska ne ovat ehdottomia kunnes ympäristö muuttuu. 1. Annotointityökalun on toimittava laitoksen koneiden Firefox- ja IE-selaimilla. 2. Järjestelmän on toimittava laitoksen Moodlen, version 1.6 kanssa. 3. Laitoksella käytettävä PHP on Fedora Coren versio 5.0.4, jota ajetaan cgi:nä. 4. Tietokantana laitoksella MySQL 4.1.16 tai PostgreSQL 7.4. 10.Tuotteen elinkaari Ohjelmiston ylläpidosta ei ole tehty suunnitelmia ohjelmistotuotantoprojektin päättymisen jälkeiselle ajalle. Ohjelmistosta tulee kuitenkin pyrkiä tekemään sellainen, että seuraava ohjelmistotuotantoprojekti pystyisi jatkokehittämään sitä. Tätä silmällä pitäen on tärkeää, että 21

ohjelmisto dokumentoidaan ja testataan hyvin. Ominaisuuksien toteuttamista resursoitaessa on muistettava, että jatkokehitystäkin ajatellen on parempi tuottaa toimiva pieni ohjelmisto kuin huonosti toimiva monipuolinen ohjelmisto. Ihannetapauksessa ohjelmistosta tulisi yksi Moodlen lisämoduuli, jota käytettäisiin ja jatkokehitettäisiin vapaaehtoisvoimin, minkä GPL-lisenssi mahdollistaa. Tähän päämäärään ei kuitenkaan erityisesti pyritä, koska se ei ole ohjelmistotuotantoprojektin tarkoitus. 22