T-76.115 Software Project: FASTAXON Personal Assignment: Documentation Practices Group: Muuntaja 0
Version History Owner of the document: Esko Simpanen Version Date Author(s) Description 0.1 28.11.2003 Esko Simpanen First Draft 0.2 29.11.2003 Esko Simpanen Chapters 3 and 4 0.3 15.3.2003 Esko Simpanen Chapter 6 1.0 4.4.2003 Esko Simpanen Released 1
Sisältö 1. Esittely...3 2. Dokumentaatio ohjelmistokehitysprojektissa...3 3. Dokumenttityypit FASTAXON-projektissa...3 3.1 Julkaistavat dokumentit...3 3.2 Sisäiset dokumentit...4 4.0 Dokumentointimenetelmät FASTAXON-projektissa...5 3.4 Asiakirjapohjat...5 3.6 Nimeämiskäytäntö ja versiointi...5 3.7 Arkistointi...5 3.8 Katselmointi- ja hyväksymismenettely...5 3.9 Julkaisu ja jakelu...6 5. Ajankäyttö...6 2
1. Esittely Tässä dokumentissa esitellään dokumentointimenetelmät ja niiden soveltuvuuden arviointi FASTAXON-projektissa. Projektissa käytettävät dokumentointimenetelmät ja dokumenttityypit on määritelty suurelta osin jo kurssin ohjeistuksessa ja osa on sovittu projektin suunnitteluvaiheessa (PP-iteraatio). Käytettäviä dokumenttityyppejä on kymmeniä ja dokumentaatio jakautuu julkaistaviin dokumentteihin ja sisäisiin ohjeisiin, seurantadokumentteihin, pöytäkirjoihin ja muistioihin. Projektin aikana on tarkoitus tutkia eri dokumenttityyppien hyviä ja huonoja puolia sekä ohjata projektiryhmän jäseniä käyttämään kuhunkin tarkoitukseen sopivaa dokumentointitapaa. Projektin lopuksi (DE-iteraatio) tehdään yhteenveto eri menetelmien toimivuudesta ja niiden luontevista käyttötavoista. Yhteenveto esitellään projektiryhmän jäsenille. 2. Dokumentaatio ohjelmistokehitysprojektissa Ammattimainen ohjelmistokehitys vaatii järjestelmällisen ja kattavan dokumentoinnin. Osa on yhteistä kaikentyyppisille projekteille, mutta ohjelmistotuotekehitysprojektin dokumentaation suuri määrä ja jatkuva päivittyvyys asettaa lisähaasteita erityisesti dokumentaation arkistointitapaan, ylläpitoon ja jakeluun. Dokumentaatio kehittyy ja versioituu läpi koko projektin, joten toimivat versiointi, katselmointi ja hyväksymiskäytännöt ja menetelmät nousevat ratkaisevaan asemaan. Varsinaisten dokumenttien lisäksi projektissa syntyvää tietoa arkistoituu erillisiin tietokantoihin, www-sivusoihin, sähköpostiviesteihin ja kommenttirivien muodossa myös itse ohjelmakoodiin. Esimerkkejä erillisiin tietokantoihin tallennetavasta tiedosta ovat mm. asiakasrekisterit, työryhmäkalenterit, työajanseurantajärjestelmät ja ohjelmistovirheiden raportointiin tarkoitetut tietokannat. Sähköpostiviestit ovat kommunikointityökalun lisäksi tapa dokumentoida projektissa syntyneitä ajatuksia ja tietoa. Tiedon pirstaloitumista hajalleen eri dokumentteihin ja arkistointipaikkoihin vähennetään hyvin suunnitellulla dokumentointikäytännöllä. Dokumentointikäytäntöjen kehittäminen parantaa tuottavuutta, sillä kommunikointi ja dokumentointi haukkaa erittäin suuren osan ohjelmistoprojektin ajankäytöstä. Aikataulujen venyessä dokumentaatio on se, josta yleensä tingitään ensimmäisenä. Tämä on vaarallista, koska koko projektin jatkokehitys tai tuotekehityksen uudelleenresursointi voi kaatua puutteelliseen dokumentaatioon tai aiheuttaa suuria kustannuksia koska jo tehtyä työtä joudutaan tekemään uudelleen. 3. FASTAXON-projekin dokumentit Projektissa käytettäviä dokumenttityyppejä on kymmeniä ja dokumentaatio jakautuu julkaistaviin dokumentteihin ja sisäisiin ohjeisiin, seurantadokumentteihin ja muistioihin. 3.1 Julkaistavat dokumentit Taulukko 1. Julkaistavat dokumentit. 3
Document Kuvaus Formaatti Omistaja Hyväksyjä name Project Plan Projektisuunnitelma. MS Word Tero Pekka Uusitalo Requirements Vaatimusmäärittely, josta käy ilmi toteutettavat ominaisuudet yleisellä tasolla. MS Word Mika Hakkarainen Tero Technical Specification Tekninen määrittely, josta toteutettavat omiaisuudet käyvät ilmi yksityiskohtaisesti MS Word Pentti Vänskä Tero Testing plan Testaussuunnitlema MS Word Pekka Uusitalo Tero Test report Julkaistava testiraportti MS Word Pekka Uusitalo Tero Test logs Testilokit MS Excel Pekka Uusitalo Tero User's manual Loppukäyttäjän ohje. MS Word Esko Simpanen Tero Progress reports Projektin etenemisraportit MS PowerPoint Tero Pekka Uusitalo Terminology and Definitions Sanasto ja terminologia MS Word Mika Hakkarainen Tero Final Report Projektin loppuraportti MS Word Tero Pekka Uusitalo 3.2 Sisäiset dokumentit Projektissa syntyy kymmeniä sisäisiä dokumentteja, joiden tallennuspaikkana käytetään CVSjärjestemää. Esimerkkejä sisäisistä dokumenteista: Työkalujen asennusohjeet Kokousten aiheet Kokouspöytäkirjat Tehtävälistat 4
4.0 Dokumentointimenetelmät FASTAXON-projektissa Tässä kappaleessa käydään läpi FASTAXON-projektissa käytetyt dokumentointimenetelmät ja käytännöt. 3.3 Työkalut ja tiedostoformaatit Julkaistavia dokumentteja ylläpidetään Microsoft Word ja PowerPoint-muodoissa. Wordasiakirjoissa olevat taulukot voidaan tarvittaessa tehdä Excelillä ja diagrammien piirtoon käytetään DIA-ohjelmaa, jolla tuotetut graafit lisätään dokumentteihin grafiikkana (ei upotettuina DIA-objekteina). 3.4 Asiakirjapohjat Julkaistavat dokumentit muotillaan ulkoasultaan yhtenäisiksi. Tätä varten ei tehdä erillistä template-dokumenttia, vaan dokumenttipohjana käytetään ensimmäistä julkaistava dokumenttia (Project Plan). Testilokeista ym. raporteista tehdään erilliset template -tiedostot. 3.6 Nimeämiskäytäntö ja versiointi Dokumentit nimetään kuvaavasti englanninkielisillä tiedostonimillä. Jokaisen dokumentin alussa on erillinen versiohistoriasivu, josta käy ilmi tehdyt muutokset. Jos mahdollista, muutoshistoriasta tulee käydä ilmi mitä kappaleita on muutettu. Tämä helpottaa dokumentin avulla kommunikointia kun dokumenttia ei tarvitse lukea alusta loppuun jokaisen muutoksen jälkeen. Jos muuttaja on muu kuin dokumentin omistaja, tiedostonimen perään lisätään kommentoijan nimi. 3.7 Arkistointi Julkaistavien dokumenttien lisäksi kaikki säilyttämisen arvoinen dokumentaatio tallennetaan natiivimuodossa (Word, Excel, Dia jne.) Niksulan palvelmella sijaitsevaan CVS-järjestelmään, johon ryhmän jäsenillä on pääsyoikeudet. CVS mahdollistaa ryhmätyöskentelyn automaattisen versioinnin avulla. Dokumenttien vanhoihin versioihin voidaan palata eikä ryhmän jäsenet tuhoa toistensa töitä tallentamalla oman version. CVS:n versionumerointi ei kuvaa dokumentin todellista versiota. 3.8 Katselmointi- ja hyväksymismenettely Jokaisella julkaistavalla dokumentilla on vain yksi omistaja ja ainakin yksi hyväksyjä. Omistaja ilmoitetaan kunkin asiakirjan alussa versiohistoriasivulla. Kun dokumentti on valmis tarkastettavaksi, omistaja ilmoittaa kaikille hyväksyjille tiedostonimen ja hakemiston CVSjärjestelmässä. Kukin tarkastaja kommentoi ja muokkaa dokumenttia ja tallentaa sen CVS:ään samaan hakemistoon siten, että tiedostonimen perään lisätään muokkaajan nimi. Muokkaukset ja kommentoinnit nähdään Wordin Track Changes, Highlight Changes toiminnolla tai ne 5
merkitään dokumenttiin eri sinisellä tekstillä. Dokumentin omistaja koostaa muokkaukset omaan alkuperäiseen dokumenttiinsa. 3.9 Julkaisu ja jakelu Projektin dokumentoinnin julkaisusta vastaava henkilö julkaisee dokumentit PDF-muodossa projektin WWW-sivulla http://www.niksula.cs.hut.fi/~esimpane/delivery.html. 5. Ajankäyttö Dokumentointisuunnitelma on tehty pääosin PP-iteraatiossa ja suunnitelman dokumentointi tarkemmin I1-iteraatiossa. Menetelmien toimivuutta ja mahdollisa korjauksia suunnitelmaan tehdään projektin aikana. DE-iteraatiossa tehdään yhteenveto eri menetelmistä ja niiden käyttökelpoisuudesta. Yhteenveto esitellään projektiryhmälle. Tehtävä Suunnittelu, PP-vaihe Suunnittelu ja dokumentointi, I1-vaihe Seuranta projektin aikana PP-DE vaiheet, 1h/iteraatio Yhteenveto, DE-iteraatio Esittely ryhmälle Tunnit 2 h 6 h 5 h 2 h 1 h Yhteensä 16 h 6. Loppuyhteenveto Projektin aikana syntyi noin 180 erillistä Word- tai Excel-dokumenttia, josta kustakin useita eri versioita. CVS-versionhallinta todettiin erittäin sopivaksi dokumentaation hallintatyökaluksi. CVS:n dokumentaation hakemistohierarkia osoittautui toimivaksi ja kullekin dokumentille löytyi sopiva tallennuspaikka. Tiedostojen nimeäminen ja versiointikäytäntö saatiin pidettyä yhtenäisenä läpi koko projektin. Dokumentaation suurella määrällä havaittiin haittapuolensakin. Päällekkäistä tietoa oli hajallaan useissa eri dokumenteissa ja tietoa hautautui dokumenttimassaan. Päällekkäisyyttä syntyi myös tuplatyöstä. Esimerkiksi kehitysympäristön asennusohjeita tehtiin peräti neljät erilliset eri henkilöiden toimesta sen sijaan, että kaikki olisivat päivittäneet samaa dokumenttia. Kurssi asetti selkeät vaatimukset dokumentaation määrälle ja laadulle. Projektiryhmä täytti nämä vaatimukset kiitettävän hyvin. 6