Ohjelmistotekniikka ja projektinhallinta, 4 op

1. Ohjelmistotekniikka ja projektinhallinta, 4 op DOkumentointi Seppo Räsänen Savonia-ammattikorkeakoulu Terveysala, kuopio 18.8.2008

2. Dokumentointi… • Ohjelmistotyöhön kuuluu oleellisena osana dokumenttien kirjoittaminen • laadukkaiden dokumenttien tuottaminen vaikeaa • Aikataulut kireitä, dokumentoinnista on helppo nipistää päiviä muuhun työhön • Määrittelyssä vaatimusten huolimaton dokumentointi voi aiheuttaa katkeria riitoja asiakkaan ja toimittajan välillä • Jos dokumentointi on puutteellista, niin esim. ohjelmiston ylläpito hankalaa… tekijäryhmän henkilöt saattavat muistaa yksityiskohdat, mutta entäpä kun henkilöstö vaihtuu

3. Dokumentointi… • Liiallinen dokumentaatio on lähes yhtä huono asia kuin dokumentaation puuttuminen • Dokumentoinnin ongelmia pyritään välttämään käyttämällä dokumenttimalleja ja katselmoimalla järjestelmällisesti tuotetut dokumentit • Dokumenttien määrä riippuu myös projektin koosta ja projektin monimutkaisuudesta • pieni projekti selviää 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… • Ohjelmistotuotannon 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 • Sopimukset, projektisuunnitelma, seurantaraportit, loppuraportti • tuotedokumentteihin • tuote/tuoteperheeseen liittyvä dokumentaatio, projektikohtaiset tuotedokumentit, tuotekohtaiset tuotedokumentit, keskeisimmät toiminnallinen määrittely, tekninen määrittely ja testausdokumentit

5. Suunnittelu Dokumentointi… tekninen määrittely integrointitestaussuunnitelma tarkennettu käyttöohje alustava ylläpito-ohje alustava operointi/huolto-ohje alustava asennusohje Esitutkimus Toteutus alustava sopimus alustava projektisuunnitelma alustava toiminnallinen määrittely alustava toteutussuunnittelu alustava testaussuunnittelu alustava tuotteenhallintasuunnitelma alustava laatusuunnitelma dokumentointisuunnitelma 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

6. Dokumentointi… Koodi versio n tekninen määrittely versio n+1 toiminnallinen määrittely versio n tekninen määrittely versio n tuotteen dokumentit tuotedokumenttien päivitys versioon n+1 projektin dokumentit projektin toiminnallinen määrittely (uudet ja muuttuneet vaatimukset) arkkitehtuurisuunnittelu projektin tekninen määrittely Evo-mallin mukaisesti etenevä dokumentaatio eri versioille

7. Dokumentointi… • Tuotetason dokumentaatio jää monesti päivittämättä • tuotteen tekninen määrittely ei ole ajantasalla • tuotetason dokumentaatio kannattaakin kirjoittaa sen verran yleisellä tasolla, ettei jokainen pikkumuutos aiheuta tarvetta päivitykseen • projektin tekninen määrittely on tarkempi ja sen päivitystarvetta ei enää projektin päätyttyä ole • 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

8. Dokumentointi… Ohjelmistohankkeen prosessi resurssit, ideat toteuttaja neuvottelut/ valmistelu asettaminen projekti/ hanke käyttöönotto käyttö asiakas tarpeet tehtävää koskevat asiakirjat tuotekansio

9. Dokumentointi… Ohjeistukset P r o j e k t i a l k a a P r o j e k t i p ä ä t t y y - projektiohje - määrittelyohje - tarkastusohje - suunnitteluohje - ohjelmointiohje - testausohje Projektiin liittyvä dokumentit 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

10. Dokumentointi… • Dokumenttimallien käyttäminen on suositeltavaa/pakollista • dokumenttien ulkoasu on aina samanlainen • dokumenteista löytyvät aina tietyt tiedot ennalta määrätyistä paikoista • Dokumentit alkavat kansilehdellä • organisaatio, projekti, dokumentin nimi, versio, sivujen lukumäärä, tekijät(t), tila • Kansilehteä seuraa tiivistelmä, sisällysluettelo, versiohistoria • Jokaisella sivulla tulisi olla sivunumero, dokumentin nimi, versionumero ja päivämäärä • Edellisestä versiosta muuttuneet kohdat tulisi selvitä versiohistoriasta • lisäksi Word:n Jäljitä –toiminnolla voidaan viimeisimmät muutokset jättää näkyviin • Osa dokumentaatiosta voi olla myös sähköisessä muodossa • Käyttöohjeet, projektin dokumentaatio voi olla hypertekstinä • Dokumenttimallit kuuluvat osana laatujärjestelmän dokumentaatiota

11. Dokumentointi… • Lähdekoodi on osa dokumentaatiota!! • lähdekoodin dokumentaatio tulee olla yhdenmukaista koko projektissa • Laatujärjestelmään liittyy yleensä tyyliopas • alkukommentit • muuttujien nimeäminen • sisennykset • koodin kommentointi • kielletyt asiat

12. Dokumentointi… Koodin dokumentointi • Miksi • koodin luettavuus paranee • koodin korjaaminen helpottuu • koodaamisvirheet vähenevät • standardointi lisääntyy • uudelleenkäytettävyys paranee • jne… • Miten • muuttujien määrittely • olioiden, luokkien, komponenttien, ohjainten nimeäminen • funktioiden (aliohjelmien) nimeäminen • sisennykset (ohjausrakenteet) • koodirivien kommentointi • aliohjelmien kommentointi • koko ohjelman kommentointi (alku, loppu, ohjelman osat) • ohjelmakoodien tallennus ja hakemistot • ohjelmien versiointi

13. Dokumentointi… • Dokumentointiin vaikuttavia standardeja • de facto (käytännön standardi) • IEEE (Institute of Electrical and Electronics Engineers) • ANSI (American National Standards Institute) • NBS (National Bureau of Standards) • NASA (National Aeronautics and Space Administration) • DoD (Department of Defence, USA:n armeija) • ISO (International Organisation of Standardization) • ESA (European Space Agency) • KOTEL (KomponenttiTeollisuuden Yhteistyöjärjestö) • SFS (Suomen Standardoimisliitto) • TIEKE (Tietoyhteiskunnan kehittämiskeskus ry)

14. Dokumentointi… laatujärjestelmä, prosessi: 1074-1991 IEEE-standardeja projektinhallinta: 1058.1-1987 määrittely: 830-1984 suunnittelu: 1016-1987 ohjelmointi testaus: 829-1983, 1008-1987 käyttö, ylläpito: 1219-1992 dokumentointi: 1063-1987 laadunohjaus: 730-1989, 983-1986, 1028-1988, 1012-1986, 1045-1992, 1061-1992, 1298-1992 tuotteenhallinta: 828-1990, 1042-1987

15. Dokumentointi… • Dokumenttipohjia, tuotettu TKV-projektissa • http://webd.savonia.fi/home/ktrasse/mat_tiedostot/thy8s/dokumenttipohjia.zip • Esitutkimus • Toiminnallinen määrittely (vaatimusmäärittely) IEEE830 • Projektisuunnitelma • Tekninen määrittely IEEE1016 • Tuotekuvaus • Testaussuunnitelma • Käyttöohje • Ylläpito-ohje

16. Dokumentointi… • Kysymyksiä • Kommentteja