Dokumentointi

1. Dokumentointi RASE 2.5.2006

2. 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

3. 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

4. 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

5. Dokumentointi • projektihallinnan dokumentteihin • sopimukset • projektisuunnitelma • seurantaraportit • loppuraportti

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

7. Dokumentointi Suunnittelu 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

8. 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

9. 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

10. 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

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

12. 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

13. Dokumentointi Ohjeistukset P r o j e k t i k ä y n t i i n P r o j e k t i p ä ä t t y 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

14. 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

15. 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

16. 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

17. Dokumentti standardit • Esimerkkejä standardeista • Toiminnallinen määrittely IEEE830 • Tekninen määrittely IEEE1016