DOKUMETTIENHALLINTASUUNNITELMA Versio 1.0 (Luonnos 1) Edited by Checked by Approved by Harri Kauhanen
i Sisällysluettelo DOKUMENTIN VERSIOT 1 1. JOHDANTO 2 1.1. Dokumentin tarkoitus ja kattavuus 2 1.2. Viittaukset muihin dokumentteihin 2 1.3. Määritelmät, termit, lyhenteet ja merkintätavat 2 2. PROJEKTIN KOTISIVU 3 2.1. Yleistä 3 2.2. Palvelimet 3 2.3. Hakemistorakenne 3 2.4. Versionhallinta 3 3. PROJEKTIDOKUMENTOINTI 4 3.1. Yleistä 4 3.2. Mallipohjat 4 3.3. Tiedostojen nimeänen 4 3.4. Asiakirjojen muotoilu 4 3.5. Versionumerostandardi 5 3.6. Dokumenttien jakaminen 6 3.7. Dokumenttien kommentointi 6 3.8. Dokumenttien julkaiseminen 7 4. TEKNINEN DOKUMENTOINTI 8 4.1. Yleistä 8 4.2. Tiedostojen sijainti ja nimeäminen 8 4.3. Tekninen suunnittelu ja mallinnus 8 4.4. Lähdekoodin dokumentointi 9 5. LÄHDEKOODI 10
ii Sisällysluettelo 5.1. Lähdekoodin versionhallinta 10
1(1) Dokumentin versiot Vers Muuttaja Pvm Muutos Tarkastanut Hyväksynyt 1.0 Harri Kauhanen 2.10.2000 Alkuperäinen versio Luonnos 1 1.0 Harri Kauhanen 7.10.2000 Tarkennettu luonnosversio Luonnos 2 1.0 Harri Kauhanen 11.10.2000 Pieniä korjauksia, joita todettiin dokumentin läpikäynnissä. Muutama kirjoitusvirhe ja täsmennys. Luonnos 3
2(2) 1. Johdanto 1.1. Dokumentin tarkoitus ja kattavuus Tämän dokumentin tarkoitus on määritellä projektiryhmälle yhteneväiset tavat hoitaa projektiin liittyvä dokumentointi, ohjelmakoodi ja niiden versionhallinta. Omaan työskentelytyyliin, nimeämiskäytäntöön jne. tottuneelle ennalta määrättyjen linjojen noudattaminen voi tuntua hankalalta. Yhteiset työskentelytavat toivottavasti kuitenkin enemmän edesauttavat kuin haittaavat projektin menestyksekästä läpiviemistä. Joitakin etuja yhteisten työtapojen ja versionhallinnan määrittelemisestä: Dokumenttien yhtenäinen ulkoasu- ja rakenne helpottavat niiden lukemista ja ymmärtämistä. Dokumentit löytyvät aina yhdestä paikasta. Dokumenttien perään ei tarvitse kysellä tai kadonneita versioita etsiskellä. Yhteisten työkalujen käyttö mahdollistaa sen, että kuka tahansa voi muokata dokumentteja. Ohjelmakoodin läpikäynti on tarkastajalle helpompaa. Työskentelyssä voidaan palata vanhoihin versioihin. Esim. kokeilujen teko on helpompaa. Saman lähdekoodin käsittely ryhmän jäsenten välillä helpottuu. Varmuuskopiointi voidaan keskittää. 1.2. Viittaukset muihin dokumentteihin Nro Dokumentti Selitys ja talletuspaikka 1 Laatusuunnitelma Laatusuunnitelma kuvaa projektin läpiviemisen laadukkaasti ja esittelee mittareita toteutuneen laadun seurantaan. 1.3. Määritelmät, termit, lyhenteet ja merkintätavat Termi, käsite, merkintätapa Versionhallinta Selitys, määritelmä Dokumenttien ja lähdekoodin hallinta siten, että kustakin tiedostosta voi versionhallintajärjestelmässä olla useita versioita. Versionhallinta mm. mahdollistaa paluun vanhaan versioon ja sen, että useampi kuin yksi pystyy työskentelemään saman lähdekoodin parissa.
3(3) 2. Projektin kotisivu 2.1. Yleistä Projektin kotisivun on tarkoitus toimia tuotetun tiedon säilytyspaikkana. Projektin luonteesta johtuen ryhmän jäsenet saattavat työskennellä eri paikoissa, joten julkiset http- ja ftp palvelimet auttavat ryhmän työskentelyä. Dokumenttien lähdekoodi (Word tiedostot) pidetään salasanan takana, mutta kaikki palautettava materiaali julkaistaan.pdf muodossa. 2.2. Palvelimet Palvelin http://hazard.iki.fi/vym ftp://hazard.iki.fi/ Selitys Projektin kotisivu. Etusivulle ja palautuksiin kaikilla vapaa pääsy, mutta jotkin osat suojataan salasanalla. Käyttäjätunnus ja salasana toimitetaan jäsenille henkilökohtaisesti. Projektin ftp palvelin. Dokumenttien jakaminen ja mallipohjien hakeminen omalle koneelle. Käyttäjätunnus ja salasana samat kuin web palvelimella. 2.3. Hakemistorakenne Hakemisto /vym/ /vym/palautukset/ /vym/src/ /vym/src/doc /vym/src/doc/template /vym/src/old/ Selitys Projektin etusivu. Palautuksille perustetaan omat kansiot. Kansiosta löytyy vähintään index.php (palautuksen etusivu) xxx.pdf (dokumentit) /src/xxx.doc (Word ja muut dokumentit, salasanalla suojattu) Kaikki mahdollinen lähdekoodi. Myös dokumenttien.doc tiedostot ajatellaan olevan lähdekoodia. Salasana suojattu. Kaikkien projektidokumenttien lähdekoodi. Dokumenteissa käytetyt kuvat (kaaviot yms.) Jokaisella dokumentilla oma kansio. Mallipohjat dokumentteja varten. Kansio yksinkertaista versionhallintaa/varmuuskopiointia varten. 2.4. Versionhallinta Dokumenttien vanhojen versioiden säilytystä varten on olemassa old kansio. Ohjelmakoodille toteutetaan oikea versionhallinta, mutta muun dokumentoinnin köyhän miehen versionhallinta perustuu eri palautusvaiheissa tehtyihin tilannekopioihin (ks. luku 3.8) ja ryhmän jäsenten omiin versiotallennuksiin old kansioon. 2.5. Varmuuskopiointi Kaikki projektin kotisivun alla olevat tiedostot varmuuskopioidaan automaattisesti kerran vuorokaudessa.
4(4) 3. Projektidokumentointi 3.1. Yleistä Projektin varsinainen dokumentointi kirjoitetaan Microsoft Word 97/2000 ohjelmalla. Pohjana käytetään soveltaen Comptelin valmiita dokumenttipohjia. Yleisesti on parempi noudattaa kurssin kotisivuilta löytyvien dokumenttipohjien rakennetta, mutta soveltaen voi myös käyttää omien dokumenttipohjien tarjoamia vinkkejä otsikointiin ja sisällöksi. 3.2. Mallipohjat Mallipohjat löytyvät projektin kotisivujen alta ja projektin FTP palvelimen alta. Käyttäjätunnukset ja salasanat toimitetaan projektin jäsenille henkilökohtaisesti. 3.3. Tiedostojen nimeänen Tiedostojen nimeämiseksi on käytössä yksinkertainen käytäntö. Dokumentin tiedostonimeksi annetaan dokumentin nimi siten että käytetään vain pieniä eiskandinaavisia kirjaimia ja välilyönnit korvataan _ (alaviiva) merkillä. Dokumentin versionumeroa ei sisällytetä tiedostonimeen. Tiedostotunniste on luonnollisesta.doc. Esimerkki hyväksyttävästä nimestä: vaatimusmaarittely.doc Nimeämistä voi erityisesti perustella sillä, että dokumentteihin saatetaan tehdä viittauksia HTML tiedostoista. Tällöin em. muodossa olevat tiedostonimet toimivat paremmin. Kommentoidut dokumentit nimetään kuitenkin kommentin tekijän mukaan lisäämällä alkuun kommentoijan nimi tai nimikirjaimet. Esim. harri_kommentit_testaussuunitelma.doc Tämä johtuu käytännön syistä, jotta jokainen voisi antaa omat henkilökohtaiset kommenttinsa. Katso lisää kappaleista 3.6 ja 3.7. 3.4. Asiakirjojen muotoilu Asiakirjojen muotoilussa on syytä käyttää tekstinkäsittelyohjelman ominaisuuksia. Tässä dokumentissa ei kuitenkaan opasteta tekstinkäsittelyn ominaisuuksia. Muutamana vinkkinä kannattaa kuitenkin muistaa seuraavat kohdat: Käytä otsikkotyylejä. Nimeä kuvat ja taulukot käyttäen Wordin luettelo-ominaisuuksia.
5(5) Käytä ristiviittauksia (älä viittaa kappaleeseen 2.3 kirjoittamalla kaksi piste kolme, vaan valitse Lisää ristiviite ominaisuus). Koeta pärjätä kolmella otsikkotasolla. Neljä on ehdoton maksimi. 3.5. Versionumerostandardi Asiakirjan sisällä pidetään kirjaa tehdyistä muutoksista. Dokumentin alkupuolella on taulukko versiohistoriasta, jota tulee päivittää aina, kun on tehty riittäviä muutoksia ja aina ennen kuin dokumentti lähetetään projektin kotisivulle. Wordin sisäistä versionhallintaa tulee käyttää vähintään silloin, kun dokumentista julkaistaan uusi hyväksytty versio. Sisäinen versionhallinta otetaan käyttöön Wordissa valitsemalla valikoista Tiedosto / Versio Standardi Versio n.m (luonnos x) Versio n.m Selite Työn alla oleva x:s luonnos tulevasta versiosta n.m Hyväksytty versio. ylivoimaisesti yleisin muoto on n.0, eli m:n arvona on nolla, muut muodot ovat korjauksia versioihin n.0 Nimen osat n m x Selite Versionumero (major). Numerointi alkaa numerosta 1 ja jatkuu 2, 3, 4, Version tarkenne (minor). kun versionumeroa vaihdetaan, tarkenne m nollataan 0:ksi. numeroita 1, 2, 3 käytetään, kun hyväksyttyyn versioon tehdään pieniä muutoksia, esim. korjataan sanamuotoja tai kirjoitusvirheitä Luonnoksen tarkenne. Numerointi alkaa numerosta 1 ja jatkuu 2, 3, 4, Esimerkki Selite Versio 1.0 (luonnos 1) Alkuperäinen, työn alla oleva luonnos tulevasta versiosta 1.0 Versio 1.0 (luonnos 2) Seuraava muokattu, mutta vielä työn alla oleva luonnos versiosta 1.0 Versio 1.0 (luonnos 3) Luonnos 2:sta edelleen muokattu => luonnos 3 Versio 1.0 Versio 1.1 (luonnos 1) Versio 1.1 Versio 2.0 (luonnos 1) Versio 2.0 (luonnos 2) Versio 2.0 Versio 3.0 (luonnos 1) Dokumentin 1.0 hyväksytty ja julkaistu versio Versioon 1.0 tehdään pieni korjaava muutos. Dokumentti on 1. luonnos tulevasta versiosta 1.1. Dokumentin 1.1 hyväksytty versio Viimeisimmän version 1.1 sisältöön tehdään muutoksia. Dokumentti on 1. luonnos tulevasta versiosta 2.0 Edellisestä on muokattu ja se on valmis kommenteille vietäväksi => luonnos 2 Dokumentin 2.0 hyväksytty ja julkaistu versio Jne.
6(6) 3.6. Dokumenttien jakaminen Dokumentteja voi kukin muokata haluamassaan paikassa. Kun dokumentti halutaan muiden tarkasteltavaksi, hyvä käytäntö on siirtää ne ensin FTP ohjelmalla projektin kotisivujen /src/doc/ kansioon ja lähettää asianosaisille linkki ko. dokumenttiin. Dokumenttien lähettämistä suoraan sähköpostin liitteenä on syytä välttää. Syyt tähän ovat ilmeiset esim. sähköpostilaatikkojen koko aiheuttaa monelle meistä ongelmia. Omalla koneella muokkauksen alla oleva dokumentti on hyvä lähettää ftp:llä projektin kotisivulle aina kun muutoksia on tehty. Näin tiedostosta tehdään aina varmuuskopio. Samassa yhteydessä tulee päivittää dokumentin sisäinen versionumero. Vaikka kyseessä olisi vain pieni muutos, niin uusi luonnos numero on annettava ja kuvattava tehdyt muutokset (ks. luku 3.5). Samasta dokumentista ei koskaan saa olla kahta erilaista versiota samalla versionumerolla (luonnos tason numerointi mukaan luettuna). Kommentoidut dokumentit tallennetaan poikkeuksellisesti asiakirjakansion alakansioon kommentit. Esim. kansio voisi olla../src/doc/laatu/kommentit/ 3.7. Dokumenttien kommentointi Valmistauduttaessa läpikäynteihin, katselmointeihin tai pienempiinkin tilaisuuksiin tarvitaan usein kommentteja muilta dokumentteihin. Pienet kommentit voidaan toki esittää suullisesti tai sähköpostitse. Monesti on kuitenkin tarvetta laajempaan kommentointiin. Tällöin pyritään käyttämään hyväksi Wordin kommentointiominaisuuksia. Seikkaperäiset ohjeet kyseisen prosessin läpiviemiseen: Kirjoittaja kaivaa Wordin työkaluista työkalupaletin Tarkistaminen. Kirjoitetaan dokumentti. Merkitään erityistä huomiota vaativat kohdat Korostus työkalulla (tekstin tausta keltainen) ja lisätään Lisää kommentti työkalulla kommentteja. Jaetaan dokumentti kappaleen 3.6 mukaisesti. Kommentoija kaivaa Wordin työkaluista työkalupaletin Tarkistaminen. Valitaan Jäljitä muutokset työkalu, jolloin tehdyt muutokset näkyvät helposti. Tehdään muutokset. Erillistä korostusta ei tarvitse yleensä käyttää. Lisätään tarvittaessa kommentteja. Tallennetaan tiedosto ja laitetaan nimen alkuun oma nimi (ks. kappale 3.3).
7(7) Siirretään kommentoitu tiedosto projektin kotisivuille dokumentin omaan kansiossa olevaan kommentit kansion alle. Alkuperäinen muokkaaja tai muutoksen tekijä hakee alkuperäisen ja kommentoidut asiakirjat itselleen. Muokkaaja lataa alkuperäisen asiakirjan. Käytetään Wordin ominaisuutta Työkalut/Yhdistä asiakirjat jokaiselle kommentoidulle asiakirjalle. Muokataan asiakirja kuntoon, versioidaan, talletetaan uusi versio, siirretään ftp:llä palvelimelle ja kerrotaan muille homman olevan tehty. 3.8. Dokumenttien julkaiseminen Ennen katselmuksia ja palautuksia perustetaan projektin kotisivulle oma kansio palatusta varten. Palautuskansion alle luodaan src kansio, johon kaikki vaihepalautukseen liittyvä dokumentaatio kopioidaan. Tämän on tarkoitus toimia hyvin yksinkertaisena dokumenttien versionhallintana. Julkaistavat dokumentit muunnetaan Adobe Acrobat (.pdf) muotoon ja siirretään kunkin vaiheen omalle palautussivulle. Jokaista palautusta varten laaditaan kurssin etusivulta linkki palautussivulle (HTML). Kaikki palautukset ovat siis yleensä joko.pdf muodossa ja tarvittaessa voidaan käyttää myös HTML muotoa. Tätä prosessia ei tarkemmin määritellä, mutta julkaiseminen on pääasiassa laatuvastaavan ja projektipäällikön vastuulla.
8(8) 4. Tekninen dokumentointi 4.1. Yleistä Tässä osassa teknisellä dokumentoinnilla tarkoitetaan kaikkea muuta kuin tekstinkäsittelyohjelmalla tuotettua dokumentointia tai ohjelman lähdekoodia. Sen sijaan tässä osassa kuvattua teknistä dokumentointia voi käyttää normaalin dokumentoinnin apuna esimerkiksi kuvina tai varsinaisen dokumentin liitteenä. 4.2. Tiedostojen sijainti ja nimeäminen Syntyvien tiedostojen nimeämiselle ei ole muuta sääntöä, kuin että nimen on syytä olla riittävän kuvaava. Esimerkiksi jos dokumentti sisältää Profiili luokan luokkakaavion, niin nimestä olisi käytävä riittävän selvästi luokan nimi ja se, että kyseessä on luokkakaavio. Joissakin tapauksissa tiedostotunniste voi olla riittävä kuvaamaan dokumentin tyypin, mutta yleensä tarvitaan tarkennuksia sopivaa nimeä valittaessa. Nimen kirjoitusasun tulisi noudattaa kappaleessa 3.3 esitettyä tapaa eli käytetään vain pieniä kirjaimia ja välilyönnit korvataan alaviivalla. Tiedostojen sijainti on tapauskohtainen, eikä sille voi esittää yksiselitteisiä sääntöjä. Paras sääntö on se, että tiedostot tulee tallettaa mahdollisimman tarkoituksenmukaiseen paikkaan. Mitä tämä milloinkin tarkoittaa on tulkinnanvaraista, mutta joitakin suuntaviivoja voimme tässä yrittää esittää. Tyyppi Yksittäinen kuva/kaavio, joka liittyy ensisijaisesti varsinaiseen dokumenttiin. Laajempi tekninen kokonaisuus, jonka kuviin/kaavioihin viitataan useista dokumenteista. Mahdollinen talletuspaikka Talletetaan samaan kansioon varsinaisen dokumentin kanssa. Esim. projektisuunnitelmaan liittyvä organisaatiokaavio voisi olla esimerkki tällaisesta tapauksesta. Mikäli kuvia on paljon (>5) niin kuvia varten on syytä perustaa oma alikansio. Perustetaan /src/doc/ alle oma kansio, johon dokumentit talletetaan. Esimerkiksi koko projektin luokkakaavio on kokonaisuus, joka vaatinee oman kansion. Joskus kokonaisuus on ratkaisevan iso ja silloin voidaan kansio perustaa suoraan /src/ kansion alle. Esimerkiksi ohjelman lähdekoodi edustaa tällaista isoa kokonaisuutta. Oleellista on kuitenkin se, että muutkin kuin Word ohjelmalla tuotetut dokumentit on syytä tallettaa projektin hakemistojärjestelmään. Vaikka tehty kuva/kaavio näkyisikin Wordissa, voi sen päivittäminen tulla myöhemmin kysymykseen. Turhalta etsimisvaiheelta vältytään, kun kaikki tarvittavat tiedostot ovat saatavilla. 4.3. Tekninen suunnittelu ja mallinnus Projektin suunnittelun eri käytetään UML mallinnusta. Mallien tuottamisen apuna käytetään Rational Rose ohjelmistoa. Ohjelmistolla tuotettuja kuvia ja kaavioita käytetään yleensä varsinaisissa dokumenteissa kuvina tai liitteinä. Itsenäisesti ne toimivat toteutuksen apuna ja mahdollisuuksien mukaan voidaan käyttää myös
9(9) ohjelmiston tarjoamia työkaluja esimerkiksi automaattisen koodirungon tuottamiseen luokkakaaviosta. Myös muita työkaluja voidaan käyttää niiltä osin, kun Rosen ominaisuudet eivät riitä tai jos mallintaminen on ratkaisevasti helpompaa. 4.4. Lähdekoodin dokumentointi Lähdekoodin tekninen dokumentointi tehdään suoraan lähdekoodiin käyttäen JavaDoc merkintöjä. Näistä merkinnöistä tuotetaan myöhemmin automatisoituja työkaluja käyttäen HTML ja/tai Adobe Acrobat tyyppiset dokumentit. Suoraan lähdekoodiin sisällytettävät JavaDoc merkinnät esitetään luvussa 5.
10(10) 5. Lähdekoodi Tämä osa kirjoitetaan myöhemmin. 5.1. Lähdekoodin versionhallinta Kirjoitetaan myöhemmin.