Dokumentointikäytännöt

Transkriptio

1 Teknillinen korkeakoulu T Tietojenkäsittelyopin ohjelmatyö Lineaaristen rajoitteiden tyydyttämistehtävän ratkaisija L models Dokumentointikäytännöt Jouni Karppinen Versio Päivämäärä Tekijä Muutokset Jouni Karppinen Ensimmäinen alustava versio Jouni Karppinen Pieniä lisäyksiä ja muutoksia tekstiin Jouni Karppinen Lisäyksiä tekstiin. Dokumenttipohja otettu käyttöön Jouni Karppinen Lisätty PP-vaiheen arviointi Jouni Karppinen Tekstiä viilattu henkilökohtaisen harjoituksen esittämistä varten Jouni Karppinen Dokumentti hiottu kuntoon ensimmäistä palautusta varten Jouni Karppinen Lisätty I1-vaiheen arviointi Jouni Karppinen Lisätty I2-vaiheen arviointi Jouni Karppinen Lisätty I3-vaiheen arviointi Jouni Karppinen Lisätty loppuarviointi.

2 Sisällysluettelo 1 Johdanto Suunnitellut käytännöt Tarkastukset ennen palautuksia Yhtenäinen ulkoasu Ymmärrettävyys Toteutus ja arviointi vaiheittain Suunnitteluvaihe (PP) Käytetyt työkalut Dokumenttien tarkastus Ensimmäinen toteutusvaihe (I1) Käytetyt työkalut Dokumenttien tarkastus Toinen toteutusvaihe (I2) Dia-työkalu Dokumenttien tarkastus Kolmas toteutusvaihe (I3) Loppuarvio ja pohdintaa... 8

3 1 Johdanto Dokumentaatio on tärkeä osa jokaista ohjelmistoprojektia. Ensinnäkin sen avulla kaikki sidosryhmät voidaan pitää ajan tasalla projektin etenemisestä. Näin mm. asiakas näkee heti, etenevätkö asiat suunnitellulla tavalla ja pääsee vaikuttamaan päätöksiin ajoissa. Tämän takia dokumentaatiota täytyy tuottaa jatkuvasti heti projektin alusta lähtien. Toiseksi projektiin osallistumattomat henkilöt, kuten loppukäyttäjät ja mahdolliset jatkokehittäjät, saavat helposti kattavan kuvan tuotteesta dokumentaation avulla. Asiakirjat ovat myös sopimuksiin verrattavaa materiaalia, jonka avulla pystytään jälkeenpäin määrittämään (esim. riitatilanteissa), ovatko osapuolet täyttäneet velvollisuutensa. Koska dokumentaatiota kertyy suuri määrä, on sen sisältö ja jaottelu pystyttävä pitämään loogisena ja yhdenmukaisena. Kolmantena seikkana tämä kurssi on oppimistapahtuma, jossa dokumentein osoitetaan opittuja asioita kurssin henkilökunnalle. Ne ovat myös tärkeä pohja arvostelulle sekä mentorille että asiakkaalle. Kaiken yllämainitun vuoksi dokumentointiin kiinnitetään erityistä huomiota tässäkin projektissa. Dokumentoinnin hallinnasta vastaa tässä projektissa Jouni Karppinen, joka valvoo asiakirjojen tuottamista tässä tekstissä esitettyjen periaatteiden pohjalta. Ensin esitellään käytännöt, joita projektiryhmä sitoutuu noudattamaan mahdollisuuksien mukaan. Sen jälkeen pohditaan vaiheittain käytäntöjen toteutumista. Projektin lopuksi suoritetaan kokonaiskatsaus dokumentointikäytäntöjen onnistumiseen. 1

4 2 Suunnitellut käytännöt Dokumentoinnin hallintaan pyritään käyttämään tässä luvussa esitettyjä käytäntöjä. Osa niistä saattaa tuntua itsestäänselvyyksiltä, mutta niiden kirjaaminen tähän osoittaa, että ne on varmasti otettu huomioon. Käytännöistä ja työkaluista järjestetään tarvittaessa koulutusta ryhmän jäsenille. 2.1 Tarkastukset ennen palautuksia Kun ryhmä katsoo kunkin vaiheen lopussa dokumenttien olevan ensimmäisen kerran sisällöltään valmiita palautukseen, niille suoritetaan tarkastus. Palautettavien asiakirjojen pitää olla valmiita vähintään yhtä vuorokautta ennen palautuksen takarajaa, jotta tarkastajille ja korjauksiin jää riittävästi aikaa. Vähintään kaksi henkilöä kokoontuu yhteen ja lukee kaikki dokumentit yhdessä huolellisesti läpi etsien niistä: kirjoitus-, kielioppi- yms. virheet asiavirheet ja sisäiset ristiriidat toiston asiakirjojen välillä puuttuvat asiat Ensimmäiseen kohtaan käytetään mahdollisuuksien mukaan myös automaattisia oikolukutyökaluja. On välttämätöntä, että vähintään kaksi henkilöä suorittaa tämän oikoluvun, sillä ihmiset ovat sokeita omille virheilleen, ja jokaisen ryhmän jäsenen voidaan olettaa kirjoittavan ainakin pienen osan kunkin kierroksen dokumentaatiosta. Näin jokainen teksti tulee tarkastettua vähintään kerran tehokkaasti ja suurin osa kahteen kertaan. Lisäksi oikolukijoiden pitäisi olla samat yhden kierroksen jokaiselle dokumentille, jotta toisto eri asiakirjojen välillä huomattaisiin. Toiston karsimiseksi päätetään yhdessä, mihin toistuva osio kannattaa sijoittaa, ja viitataan toisista dokumenteista sinne. Tässä käytetään apuna tarvittaessa jonkinlaista koodausta. Esim. vaatimusmäärittelyn vaatimuksille annetaan numerokoodit jokaiselle viittausta helpottamaan. 2.2 Yhtenäinen ulkoasu Yhtenäinen ulkoasu ja rakenne helpottaa dokumenttien lukemista ja antaa niistä laadukkaan vaikutelman. Siksi käytämme valmista dokumenttipohjaa, joka määrittelee asiakirjojen tyylin. Mahdollisimman pitkälle viety asiakirjapohja vähentää myös käsin tehtävää dokumenttien muotoilua, kun tyylit, sijoittelu yms. on määritelty jo valmiiksi. Uusia tyylejä ja muita muutoksia voidaan tehdä projektin aikana asiakirjapohjaan joustavasti ja tarpeen mukaan. Ne heijastuvat välittömästi kaikkiin työn alla oleviin ja tuleviin dokumentteihin. Aikaisemmin palautettuja dokumentteja ei muokata enää ulkoasun takia, ellei niitä jouduta päivittämään muutenkin. Dokumentit kirjoitetaan OpenOffice.org-tekstinkäsittelyohjelmalla. UML- ja mahdollisuuksien mukaan muutkin kaaviot piirretään Dialla. Näitä valintoja on perusteltu tarkemmin projektisuunnitelmassa. Valmiit dokumentit muutetaan palautettaessa PDFmuotoon. 2

5 2.3 Ymmärrettävyys Tekstistä pyritään muokkaamaan mahdollisimman helppolukuista ja ymmärrettävää. Näin varmistetaan, että eri sidosryhmät voivat käyttää dokumentteja tehokkaasti hyväkseen taustatiedoista riippumatta. Tämä on tärkeää myös mahdollista jatkokehitystä ajatellen, sillä ei voida tietää varmasti, millaiset henkilöt dokumentteja lukevat joskus tulevaisuudessa. Ymmärrettävyyden tärkeyttä korostaa myös projektin luonne, sillä monien asioiden pohjana on tavalliselle ihmiselle vaikeaselkoisia muodollisia määrittelyjä. Ymmärrettävyydestä huolehtii ensisijaisesti Jouni Karppinen. Tarvittaessa epäselvän, liian teknisen tai huolimatonta slangia sisältävän tekstin kirjoittajalta kysytään selvennystä. Erityistä huomiota kiinnitetään englannista väännettyihin sanoihin, jotka eivät ole hyvää suomea. Tarpeellisia teknisiä termejä voidaan myös selittää erillisissä sanastoissa dokumenttien yhteydessä. 3

6 3 Toteutus ja arviointi vaiheittain Tässä luvussa arvioidaan käytäntöjen toimeenpanon onnistumista sekä niiden vaikutusta projektiin. Arviointia tehtäessä olisi mahdollista käyttää kvantitatiivisia mittareita, joista näkisi helposti käytäntöjen onnistumisen. Tällaisten tulosten analysointi olisi kuitenkin vaikeampaa, kuin miltä saattaa näyttää. Voisi luoda kategorioita ja laskea vaiheittain virheiden ja korjauksien määrän, mutta mitään vertailutietoa ei saisi siitä, millainen tulos olisi ollut ilman käytäntöjä. Sitäkään ei kenties saa tietää, paljonko puutteita dokumentteihin lopulta jää. Siksi tällä kertaa päädyttiin arvioimaan tuloksia vapaamuotoisesti sanallisesti. Vaiheiden PP, I1, I2 ja I3 lopussa suoritetaan lyhyt arviointi toteutuneiden seikkojen pohjalta sekä pohditaan kehittämismahdollisuuksia. Näitä parannuksia pyritään ottamaan käyttöön jo kesken projektin. Lisäksi projektin lopussa tehdään yhteenveto käytäntöjen onnistumisesta. 3.1 Suunnitteluvaihe (PP) Ensimmäisen vaiheen jälkeen voidaan todeta, että suunnitellut käytännöt otettiin onnistuneesti käyttöön, mutta vastaan tuli lukuisia ongelmia, jotka on pyrittävä jatkossa korjaamaan Käytetyt työkalut Alkuperäinen dokumenttipohja sisälsi vain kaikkein välttämättömimmät määrittelyt, joiden avulla asiakirjoja päästiin kirjoittamaan. Seuraavaan vaiheeseen pohjaa on tehtävä monipuolisemmaksi tässä vaiheessa ilmenneiden puutteiden pohjalta. Mm. kuvatekstien tyyliä ei ollut vielä määritelty. OpenOffice.org-ohjelmassa on ilmennyt pieniä eroja toisaalta versioiden 1.0 ja 1.1 välillä ja toisaalta Windows ja Linux -ympäristöissä. Erot versioiden välillä ovat marginaalisia eivätkä vaadi mitään toimenpiteitä. Varsinaisesti käytämme versiota 1.1, mutta koulun koneilla on vielä vanha versio. Ympäristöjen välillä ongelmaksi muodostui se, ettei niissä ole valmiina samoja fontteja. Siksi dokumenteissa tuli Linux-ympäristössä joitakin kauneusvirheitä, kuten taulukoissa rivin viimeinen kirjain saattoi pudota seuraavalle riville. Puuttuvien fonttien lisäämistä tutkitaan seuraavassa vaiheessa. Myös Diassa ilmeni ongelmia, ja ne olivat jo vakavia. Käytössä on useita eri versioita, ja niiden yhteensopivuus näyttää heikolta. Seuraavassa vaiheessa selvitetään, onko mahdollista, että kaikki käyttävät jotain tiettyä versiota, jos kunnolla eri ympäristöissä toimiva versio löydetään Dokumenttien tarkastus Valmiiden dokumenttien tarkastus vaiheen lopussa onnistui kohtalaisesti. Varsinkin kirjoitus- ja kielioppivirheitä löytyi runsaasti. Kumpikin tarkastajista löysi myös muutaman korjattavan kohdan, jota toinen ei nähnyt. Tämä osoittaa hyväksi ideaksi sen, että kaksi ihmistä tarkastaa dokumentit. Henkilöt pystyivät myös neuvottelemaan keskenään korjauksista, jolloin uusia virheitä ei pääse syntymään niin helposti vanhojen tilalle. Tarkastuksessa ilmeni myös joitakin ongelmakohtia. Pienin näistä on se, että on vaikeaa kiinnittää lukiessa huomiota kaikkeen samalla kertaa. Helposti huomio kiinnittyy vain kirjoitusvirheisiin, ja sisältö kokonaisuutena jää vähemmälle huomiolle. Tähän on vaikea 4

7 keksiä muuta korjausta, kuin useampi läpikäynti keskittyen yhteen asiaan kerrallaan. Tähän ei kuitenkaan ole resursseja, eikä hyötykään olisi luultavasti riittävän suuri perustelemaan tätä. Resursseja kului nytkin jo enemmän kuin oli arvioitu. Suunnitellun neljän tunnin sijaan tarkastukseen meni aikaa yhteensä kuusi tuntia. Tämä näkyi pienenä väsymyksenä viimeisen asiakirjan kohdalla. Jos seuraavassa vaiheessa tarkastettavien dokumenttien määrä antaa siihen aihetta, asiaa pyritään helpottamaan jakamalla tarkastus kahteen osaan ja vaihtamalla toista tarkastajaa osien välillä. Toisen henkilön on kuitenkin pysyttävä samana, jotta eri asiakirjojen väliset ongelmat löydetään. Kolmas huomautus koskee aikataulua, jota ei pystytty aivan pitämään. Osa dokumenteista valmistui vasta samalla, kun tarkastus oli jo käynnissä. Onneksi tarkastusta ei tarvinnut missään kohdassa keskeyttää, vaan asiakirjat saatiin juuri ajoissa valmiiksi. Myös asiakas huomautti viivytyksestä, sillä hän olisi halunnut tutustua valmiisiin dokumentteihin ja kommentoida niitä ajoissa. Seuraavassa vaiheessa aikataulussa pysymiseen kiinnitetään tarkemmin huomiota. 3.2 Ensimmäinen toteutusvaihe (I1) Tässä vaiheessa suurimmat ongelmat koskivat aikataulussa pysymistä. Myös muuta pientä ilmeni runsaasti, mutta kaikesta suoriuduttiin kunnialla ja ilman pahoja takaiskuja Käytetyt työkalut Dokumenttipohjaan saatiin nyt kaikki tarpeellinen lisättyä, ja sitä voitaneen pitää lopullisena. OpenOfficen kanssa havaittiin kuitenkin pieniä ongelmia muotoseikoissa. Ohjelma haluaa nähtävästi varata kokonaisen uuden aukeaman yhden sivun sijaan, jos sisällysluettelo ei mahdu yhdelle sivulle. Siksi projektisuunnitelmassa on ylimääräinen tyhjä sivu, jonka poistamiseen ei ainakaan vielä löytynyt suoraa keinoa. Dokumenttipohjasta on kadonnut määrityksiä joillakin henkilöillä. Tyylimääritykset oli helppo korjata ennalleen. Teknisestä määrittelystä oli kuitenkin poissa myös sivujen ala- ja yläreunojen poikkiviivat, jotka eivät tuntemattomasta syystä suostuneet korjaantumaan. Myöhemmin palautuksen jälkeen tämä tuntui korjaantuneen itsestään. Dialle oli varmasti eniten käyttöä tässä vaiheessa, kun tekniseen määrittelyyn tehtiin kaikki UML-kaaviot. Olimme onnistuneet karsimaan käyttämämme versiot kolmeen, jotka olivat jossakin määrin keskenään taaksepäin yhteensopivia. Näin saimme kaiken tarpeellisen piirrettyä suuremmitta ongelmitta kolmen henkilön voimin. Päivityksiä kaavioihin varmasti vielä tarvitaan, ja näihin meillä on jäänyt jäljelle yksi tai kaksi versiota, joilla niitä voidaan tehdä piirtämättä diagrammeja kokonaan uusiksi Dokumenttien tarkastus Tällä kertaa ensimmäiset versiot saatiin asiakkaan tutkittaviksi hyvissä ajoin. Kenties juuri tämän ansiosta vaatimusmäärittely saatiin nyt asiakastakin tyydyttävään kuntoon. Asiakkaan toivomuksesta ja muutenkin asiakirjoihin tuli vielä reilusti muutoksia, ja valitettavasti näitä ei taaskaan onnistuttu toteuttamaan aivan ajoissa tarkastusta varten. Tarkastus jouduttiin nimittäin jakamaan kolmeen palaseen, kun viimeiset muutokset valmistuivat vasta palautuspäivää edeltävänä iltana. Onneksi toinen tarkastaja saatiin mukaan joka kerralla, mutta toista jouduttiin vaihtamaan. Yksi dokumentti piti katsoa läpi 5

8 aivan yksin. Kaiken kaikkiaan aikaa kului vähän enemmän kuin ensimmäisessä vaiheessa, ja samalla myös vähän ennakoitua enemmän. Jatkossakin vastaavaa saattaa sattua, sillä ajankäyttötiedot edistymisraporttiin saadaan vasta aivan viime hetkellä. Tämä johtuu siitä, että mm. juuri tarkastukseen kuluva aika pitäisi myös saada kohtalaisen tarkasti otettua huomioon. Parantamisen varaa tämän vaiheen toimintaan kuitenkin jäi. Kaikessa kiireessä sattui vielä sellainen kömmähdys, että etenemisraportista palautettiin korjaamaton versio. Onneksi siinä ei ollut pahoja virheitä. Huomasimme silti, että palautusta ei kannata jättää viime hetkeen, jolloin turha hermoilu voi aiheuttaa jotain tällaista. Yhä selvemmin kävi ilmi, että tarkastuksissa ei pystytä kunnolla arvioimaan tekstejä suurina kokonaisuuksina. Ihminen ei vain pysty käsittelemään asioita monella tavalla samanaikaisesti. Siksi sisällöllisten seikkojen huomiointi joutuu pikkuisen kärsimään mm. kieliopillisen virheettömyyden takia. Toisaalta tiedämme asiakkaan keskittyvän juuri sisältöön omissa kommenteissaan, joten niistäkin saadaan palautetta. 3.3 Toinen toteutusvaihe (I2) Tässä vaiheessa asiat sujuivat selvästi paremmin kuin aikaisemmissa ja ilman merkittäviä ongelmia. Tarkastusmenetelmää saatiin parannettua vähän, kun mm. huomattiin, ettei kaikkeen kannata käyttää kahden ihmisen aikaa Dia-työkalu Dian käytöstä tehty ratkaisu saatiin lopulta tehtyä ja kirjattua myös projektisuunnitelmaan. Uudet diagrammit tehtäisiin ATK-keskuksen koneilla, ja vanhoja päivitettäisiin Joonaksella käytössä olevalla versiolla. Kaiken kaikkiaan Dia on osoittautunut huonoksi valinnaksi, mutta olemme sentään saaneet kaiken tarpeellisen tehtyä sen avulla Dokumenttien tarkastus Dokumentit valmistuivat tällä kertaa hyvin aikataulussa. Koska muutoksia oli tehty hyvin vähän iteraation aikana, ei myöskään tarkastamiseen tarvittu enää niin paljon aikaa. Minulta itseltäni kului silti useita tunteja kaikenlaiseen pieneen, kuten dokumenttien muuttamiseen oikeaan formaattiin ja palautuksen tekemiseen. Toinen syy tähän ajan kulumiseen oli se, että katsoimme mielekkäämmäksi käydä joitakin dokumentteja vain yksin läpi. Näitä olivat reviewkalvot, joiden merkitys dokumenttina on muita vähäisempi, ja testiraportti, joka oli lyhyt ja muodoltaan määrätty. Kun varsinaisia muutoksia ja sitä kautta virheitä oli vähän, huomasimme, että teknisessä määrittelyssä pystyimme keskittymään vähän paremmin sisällönkin arviointiin. Sieltä havaittiin joitakin kohtia, jotka esim. tekivät dokumentista tarkastajien mielestä vaikeaselkoisen. Ongelmakohdat kirjattiin ylös, mutta niitä ei alettu muuttamaan, sillä tarkastajien olisi ollut huomattavasti vaikeampaa tehdä se kuin asiakirjasta vastaavan henkilön. 3.4 Kolmas toteutusvaihe (I3) Tässä vaiheessa dokumentteihin tehtiin hyvin vähän muutoksia. Siksi parina tehtävästä tarkastuksesta päätettiin tämän vaiheen kohdalla luopua kokonaan, ja tarkastus tehtiin 6

9 yksin ja vain muuttuneisiin kohtiin. Muutenkin aikaa kului tällä kertaa vähän. Osa vähemmän tärkeistä asiakirjoista jätettiin kokonaan tarkastamatta. Näitä olivat lähinnä vertaistestaukseen liittyvät suunnitelmat ja raportit. Perusteina olivat resurssien säästäminen, dokumenttien vähäinen merkitys ja se, että emme olleet itse edes luoneet kaikkia dokumentteja. 7

10 4 Loppuarvio ja pohdintaa Tässä luvussa arvioidaan dokumentoinnin ja sen käytäntöjen onnistumista koko projektin tasolla projektin päättyessä. Ensin käsitellään kukin kolmesta käytännöstä yksitellen. Viimeiseksi esitetään vielä lyhyt yleisarvio dokumentointikäytäntöjen hyödyllisyydestä kokonaisuutena. Tähän lukuun on liitetty myös muille ryhmän jäsenille tehdyn kyselyn tuloksia. Kysymykset olivat: Kannattiko näitä dokumentointikäytäntöjä mielestäsi käyttää tässä projektissa? Kuinka paljon huonompaa jälkeä olisi tullut ilman niitä (voit esim. verrata muihin kokemuksiisi)? Asteikolla 1-5 (5=paras), kuinka laadukkaina pidät tähän mennessä tekemiämme dokumentteja? Vastaa, jos olit mukana pareittain tehtävissä tarkastuksissa: Koitko ne hyödyllisiksi? Entä suhteessa käytettyyn aikaan? Oliko niissä mielestäsi jotain parannettavaa? Vastaa, jos käytit jossain vaiheessa hyväksesi dokumenttipohjaa (myös dokumenttipohjaa käyttävien dokumenttien päivittäminen lasketaan): Oliko se mielestäsi hyvä ja tarpeeksi kattava? Jos ei, niin mitä puutteita siinä oli? Kuinka monta tuntia käytit tällä kurssilla OpenOfficen opetteluun? Ovatko tekemämme dokumentit (erityisesti tekninen määrittely) riittävän ymmärrettäviä ja helppolukuisia, ottaen huomioon aiheemme teoreettisen vaativuuden? Näetkö jonkin helpon keinon, jolla niitä olisi voinut parantaa tässä suhteessa? 4.1 Tarkastukset ennen palautuksia Tarkastuksia hankaloitti dokumenttien viivästeleminen useassa iteraatiossa. Niitä jouduttiin siirtämään aiotuista ajoista, mutta loppujen lopuksi aikaa aina löydettiin ja kaikki tarkastukset saatiin tehtyä. Itse tarkastuksissa esiin tulivat ennen kaikkea kirjoitus- ym. pienet virheet. Kokonaisuuteen ei sen sijaan pystynyt kiinnittämään samalla riittävästi huomiota. Vasta aivan projektin lopussa tämä parani hieman, kun asiakirjojen muutokset ja sitä kautta virheet olivat vähentyneet huomattavasti. On kuitenkin todettava, että tällaiset katselmukset näyttävät olevan hyödyllisiä lähinnä kieliasun korjaamiseen. Sen tärkeyttä ei silti sovi väheksyä. Tarkastaminen kahdestaan vaikuttaa edelleen hyvältä ajatukselta, ainakin projektin alkupuolella, sillä virheitä tuntui löytyvän jonkin verran enemmän kuin yksin. Korjauksista saattoi myös keskustella toisen kanssa, jolloin niitä oli helpompi tehdä saman tien. Toisaalta aikaa kului melko paljon, ja ajankäyttöä olisi voinut ehkä tehostaa siten, että tarkastajat olisivat tutustuneet dokumentteihin etukäteen yksinään. Ensimmäisissä iteraatioissa tarkastajia oli kaksi, mutta loppua kohti tarkastamisen tarve väheni. Ensin osa tarkastettiin vain yksin ja I3-iteraatiossa jo kaikki. Tätä valintaa tukee myös kaavio 1, joka esittää tarkastuksiin tarvittua aikaa tunteina kussakin vaiheessa. Siinä on eroteltu itseni sekä toisen tarkastajan käyttämät tunnit. 8

11 Muiden tunnit Omat tunnit PP I1 I2 I3 Kaavio 1: Tarkastuksiin käytetty aika iteraatioittain. 4.2 Yhtenäinen ulkoasu OpenOffice osoittautui hyväksi työkaluksi, jota kaikki ryhmän jäsenet käyttivät. Osalle ryhmän jäsenistä se oli tuttu ennestään, mutta melkein jokaiselta meni tunti pari sen kanssa orientoitumiseen. OpenOfficen käytön opetteluun käytettiin nimittäin yhteensä 25 tuntia, josta itseltäni kului puolet. Minun suuri osuuteni johtuu tietysti siitä, että jouduin opettelemaan ohjelman toimintoja melko tarkasti, jotta pystyin tekemään dokumenttipohjan. Dian kanssa tuli versioiden yhteensopivuusongelmia, mutta niistä selvittiin lopulta joten kuten. Ongelmia oli myös Dian kaavioiden siirtämisessä OpenOfficeen. Tämä työkalu oli huono valinta, mutta se oli ainoa UML-kaavioiden piirtämiseen soveltuva ohjelma, joka on sekä ilmainen että toimii sekä Windowsissa että Linuxissa. Dokumenttien yhtenäinen ulkoasu koettiin ryhmän sisällä hyvin positiivisena asiana. Eräiden kommenttien mukaan yrityksissä laatu jää varsinkin projektien alkuvaiheessa helposti huonolle tasolle. Tämä puolestaan antaa asiakkaalle kehnon vaikutelman, jota on myöhemmin vaikea korjata. Joidenkin mielestä dokumenttipohjassamme oli pieniä puutteita, mm. valmiiden määritysten kattavuuden suhteen. Keskimäärin se koettiin kuitenkin riittävän hyväksi sekä kattavuudeltaan että ulkoasultaan. 4.3 Ymmärrettävyys Tämä käytäntö oli oikeastaan kokonaan vain minun harteillani. Se ilmeni vaikeaksi arvioida ja toteuttaa. Kun samojen tekstien kanssa on jatkuvasti tekemisissä, niihin menettää auttamattomasti sellaisen kosketuksen, joka ensi kertaa lukevalla on. Suurin haasteemme oli tekninen määrittely. Se on jatkokehitystä ajatellen tärkein dokumenttimme, ja aiheemme teoreettisen vaativuuden vuoksi vaikein saada helposti ymmärrettävään muotoon. Niinpä sen kohdalla ryhmämmekin mielipiteet jakautuivat. Joidenkin mielestä dokumentti oli riittävän hyvä ja lukijalta voidaan odottaakin pohjatietoja aiheesta. Muiden mielestä sen sijaan parantamisen varaa jäi mm. laajuuden, ymmärrettävyyden ja esittelytavan suhteen. Teknisen määrittelyn parantamista nykyisestä ei kuitenkaan pidetty helppona tehdä, joten voinemme olla tyytyväisiä tulokseen. Kieliasu saatiin joka tapauksessa hyvään kuntoon kaikissa dokumenteissa, mihin olen itse hyvin tyytyväinen. 9

12 4.4 Yleisarvio hyödyllisyydestä Kaikkien ryhmämme jäsenten mielestä käytännöt olivat hyödyllisiä ja niitä kannatti ehdottomasti käyttää tässä projektissa. Ilman niitä dokumenttien laatu olisi ollut huonompi, erityisesti alussa. Kysyttäessä yleisarvosanaa dokumenttiemme laadulle asteikolla 1-5, saatiin keskiarvoksi 3,7, eikä yksikään yksittäinen arvio jäänyt alle kolmen. Myöskään asiakas tai mentor ei ole joutunut huomauttamaan dokumenteistamme muuten kuin sisällön (ja teknisen määrittelyn kohdalla ehkä sisällön selkeyden) vuoksi. Lisäksi olen itse oppinut näiden käytäntöjen kautta uusia asioita, kuten uusia työkaluja ja kohtaamaan käytännön ongelmia. Näillä perusteilla voin päättää sanomalla, että dokumentointikäytäntömme olivat pitkälti onnistuneita ja kaikin puolin hyödyllisiä tässä projektissa. 10