Dokumentointi RASE 2.5.2006

Ohjelmistotyöhön kuuluu oleellisena osana dokumenttien kirjoittaminen Dokumentointi Ohjelmistotyöhön kuuluu oleellisena osana dokumenttien kirjoittaminen dokumentoinnin avulla asiakas ja toteuttaja sopii kehitettävän järjestelmän sisällön, projektin toteutuksen, jne. laadukkaiden dokumenttien tuottaminen vaikeaa aikataulujen tiukkuus määrittelyssä vaatimusten huolimaton dokumentointi voi aiheuttaa katkeria riitoja asiakkaan ja toimittajan välillä jos tarkkoja tietoja ei ole dokumentoitu, niin ajan saatossa järjestelmän ylläpito ja jatkokehitys mahdotonta

Dokumentointi Liiallinen dokumentaatio on lähes yhtä turmiollista kuin dokumentaation puuttuminen Dokumentoinnin ongelmia voidaan yrittää välttää käyttämällä dokumenttimalleja ja katselmoimalla järjestelmällisesti tuotetut dokumentit Dokumenttien määrä riippuu projektin koosta ja projektin monimutkaisuudesta pieni projekti saattaa selvitä hyvinkin vähäisellä perusdokumentoinnilla aina pitäisi löytyä määrittely- ja suunnitteludokumentit myös testausdokumentaation olemassaolo helpottaa myöhempien ohjelmiston muutosten testausta

Ohjelmistotuotantoprosessin dokumentit voidaan jakaa Dokumentointi Ohjelmistotuotantoprosessin dokumentit voidaan jakaa laatukäsikirjan dokumentteihin laatukäsikirja ohjeistukset pöytäkirjat dokumenttipohjat työmääräennusteet ja vastaavat toteutumat resurssiarviot ja vastaavat toteutumat

projektihallinnan dokumentteihin Dokumentointi projektihallinnan dokumentteihin sopimukset projektisuunnitelma seurantaraportit loppuraportti

Dokumentointi tuotedokumentteihin johonkin tuotteeseen tai tuoteperheeseen liittyvä dokumentaatio projektikohtaiset tuotedokumentit tuotekohtaiset tuotedokumentit keskeisimmät toiminnallinen määrittely, tekninen määrittely ja testausdokumentit

Dokumentointi Suunnittelu Esitutkimus Toteutus Määrittely Testaus tekninen määrittely integrointitestaussuunnitelma tarkennettu käyttöohje alustava ylläpito-ohje alustava operointi/huolto-ohje alustava asennusohje Esitutkimus alustava sopimus alustava projektisuunnitelma alustava toiminnallinen määrittely alustava toteutussuunnittelu alustava testaussuunnittelu alustava tuotteenhallintasuunnitelma alustava laatusuunnitelma dokumentointisuunnitelma Toteutus moduulisuunnitelmat moduulitestaussuunnitelmat moduulitestauspöytäkirjat koodit integrointitestaussuunnitelma integrointitestauspöytäkirjat integroitu ohjelmisto tarkennettu ylläpito-ohje tarkennettu operointi/huolto-ohje tarkennettu asennusohje Määrittely tarkennettu sopimus tarkennettu projektisuunnitelma toiminnallinen määrittely alustava tekninen määrittely tarkennettu testaussuunnittelu (järjestelmä- ja hyväksymistestaus) tarkennettu tuotteenhallintasuunnitelma tarkennettu laatusuunnitelma alustava käyttöohje Testaus järjestelmätestauspöytäkirjat hyväksymistestauspöytäkirjat paketointi-ohje koulutusmateriaali tuotedokumenttien viimeistellyt versiot

Tuotetason dokumentaatio jää kiireen takia yleensä päivittämättä Dokumentointi Tuotetason dokumentaatio jää kiireen takia yleensä päivittämättä tuotteen tekninen määrittely ei ole ajan tasalla se kannattaakin kirjoittaa sen verran yleisellä tasolla, ettei jokainen pikkumuutos aiheuta tarvetta päivitykseen projektin tekninen määrittely on sitten pikkutarkempi ja sen päivitystarvetta ei enää projektin päätyttyä ole

Dokumentointi Kun projekti päättyy, projektin tuotedokumentaatio muutetaan osaksi tuotekohtaista tuotedokumentaatiota käyttöohje asennus- ja operointiohje koulutusmateriaali tekninen dokumentaatio toiminnallinen määrittely tekninen määrittely testaukseen ja tuotehallintaan liittyvät ohjeistukset

Dokumentointi Seuraavassa kuvassa on esitetty eräs tapaus ohjelmistohankkeiden prosessista alkaa asiakasneuvotteluista ja päättyy toimitukseen projektista syntyy tuotekansio tärkeimmät dokumentit ylläpitoa palvelevassa muodossa minne ja miten projektiin liittyvät ohjelmistot, kehitysympäristöt jne on arkistoitu

ohjelmistohankkeiden prosessi Dokumentointi ohjelmistohankkeiden prosessi resurssit, ideat Toteuttava yritys neuvottelut/ valmistelu asettaminen projekti/ hanke käyttöönotto käyttö Asiakas tarpeet tehtävää koskevat asiakirjat tuotekansio

Dokumentointi Seuraava kuva taasen esittää samaisen yrityksen projektiin liittyvät dokumentaatiot toimintaa ohjaavat ohjeistukset projektin hallintaan liittyvät dokumentit projektin seurannan pöytäkirjat tuotedokumentit lisäksi projekteihin liittyy myös erillinen projektipäiväkirja viikoittaiset projektipalaverit tarkastuskokousten tulokset

Projektisuunnittelu, seuranta ja ohjaus Dokumentointi Ohjeistukset P r o j e k t i ä y n P r o j e k t i p ä y - projektiohje - määrittelyohje - tarkastusohje - suunnitteluohje - ohjelmointiohje - testausohje Projektisuunnittelu, seuranta ja ohjaus alustava projektisuunnitelma tarkennettu projektisuunnitelma kokouspöytäkirjat loppuraportti määrittely tarkastukset suunnittelu tarkastukset ohjelmointi järjestelmä- testaus- suunnitelma tarkastukset integrointitestaus järjestelmätestaus toiminnallinen määrittely tekninen määrittely ohjelmakoodi testaus- raportti Katselmukset määrittely- katselmus suunnittelu- katselmus hyväksymis- katselmus pöytäkirjat

Tutustu materiaalissa mukana oleviin dokumenttipohjiin Dokumentointi Dokumenttimallien käyttäminen on erittäin suositeltavaa ja yleensä jopa pakollista dokumenttien ulkoasu on aina samanlainen ja dokumenteista löytyvät aina tietyt tiedot ennalta määrätyistä paikoista Tutustu materiaalissa mukana oleviin dokumenttipohjiin

Osa dokumentaatiosta voi olla myös sähköisessä muodossa Dokumentointi Osa dokumentaatiosta voi olla myös sähköisessä muodossa käyttöohjeet periaatteessa koko projektin dokumentaatio voi olla hypertekstinä Dokumenttimallit kuuluvat osana laatujärjestelmän dokumentaatiota myös ohjeistus mallien käytöstä oltava saatavilla ja niissä tulee kertoa mihin malli on tarkoitettu ja mitkä kappaleet/osat dokumenttimallista on pakko kirjoittaa

Lähdekoodi on osa dokumentaatiota!! Dokumentointi Lähdekoodi on osa dokumentaatiota!! yhdenmukaisuusvaatimukset vähintään yhtä korkealla tasolla kuin muissakin dokumenteissa Laatujärjestelmään liittyykin yleensä tyyliopas alkukommentit muuttujien nimeäminen sisennykset koodin kommentointi kielletyt asiat

Dokumentti standardit Esimerkkejä standardeista Toiminnallinen määrittely IEEE830 Tekninen määrittely IEEE1016