Mis on dokumentatsioon?

Tarkvara arenduse elutsüklis on olemas erinevaid tegevusi, nende tegevuste tulemusel tekib hulk artifakte mis dokumenteerib nendes tegevustes kas siis tehtavaid tegevusi või tulevasi tgevusi või tehtud tgevusi ja nende tegijaid. Dokumentatsioon tekib peaaegu igas tarkvara arenduse elutsükli etapis ja igas tarkvaraarenduse elutsükli tüübis. Need artefaktid kokku moodustavadki tarkvara dokumentatsiooni.

Milliseid artefakte dokumentatsioonis esineda võib?

On olemasa erinevaid tüüpe dokumentatsioone aga tüüpiliselt esinevad järgnevad:

• Süsteemi nõuete dokument
• Arhitektuurse disaini dokument
• Kasutajajuhend
• Projektihaldus dokumentatsioon
• Süsteemi haldusjuhend

Mida need endast kujutavad ning mis on nende eesmärgid?

Süsteemi nõuete dokument

Kujutab endast erinevates arendustsüklites oleva Analüüsietapi väljundit, kus pannakse paika arendatava süsteemi erinevad nõuded koostöös lõppkasutajatega ning kliendiga. Arvestatakse mõlemi vajadusi ning selgitatakse välja erinevad tõkestused.

Dokumendi eesmärk on anda arendajale Arhitektuurse disaini dokumentdi loomise jaoks täpne sisend selle kohta mida üldse arendama peab, selle abil kirjeldatakse juba süsteemselt arendajale vajalik info.

Mida süsteemi nõuete dokument endas sisaldama peab?

• Sissejuhatus:

Kirjeldab ära dokumendi eesmärgi (Milleks ja kellele), Projekti ulatuse (Mida arendatakse, mida mitte), Terminite sõnastik (Mittearendajale kirjeldamaks kasutatud tehnoloogilisi termineid), Viited teistele Dokumentidele (Erinevad uml diagrammid, kasutajajuhendid, meeskonna arenduse halduskeskond, projekti- juhtimise halduskeskond, Arendatava töö enda haldusjuhend, jpm)

• Toote kirjeldus:

Kirjeldab arendustööd ennast mida selle dokumendi abil arendama hakatakse/arendatakse

• Erinevate osapoolte profiilif:

Kirjeldatakse ära mida tahab kasutaja teha, mida klient sellest saab, mis on nende erinevad vajadused, kas neil on eelnevaid kogemusi sarnaste toodetega samast tootekategooriast. Nt rollipõhine tabel:

Roll	Tegevused
Külaline	Vaadata pealehte Registreerida kasutaja
Registreeritud kasutaja	Kõike mis külaline + Teha postitusi Laadida üles üilte Vaadata postitusi Saate teistele kasutajatele sõnumeid Kommenteerida postituse alla
Admin	Kõike mis registreerinud kasutaja + Kasutajaid bannida Postitusi kustutada Kommentaare eemaldada Pilte eemaldada
Süsteemi administraator	Hoolitseb veebiäpi toimimise eest, haldab andmebaase, teeb korrastustöid, vajadusel konfigureerib ja jälgib muud statistikat et tagada kliendi ja kasutajate rahulolu.

Profiilide detailne väljakirjeldamine aitab arendajatel aru saada mis tegevusi neil teha vaja on, et tagada vastav funktsionaalsus lõpptootes.
• Piirangud:

Kirjeldatakse ära erinevad piirangud või tõkestatavad aspektid, mis võivad arendusel ette tulla, kasutajatel endal olla, keskkonnast kus toode toimima peab, arendusvahenditest tulenevad piirangud ja seaduslikud piirangud

• Erinevad eeltingimused/sõltuvused:

Toote loomist võib tingida mingisugune eelnev tingimus - viiakse sisse riigisüsteemis mingisugune muudatus, digitaalne vahend selle jaoks puudub, ning leitakse et on vaja arendada vastav tööriist, et tagad riigisüsteemi muudatuse ülalhoid.

• Käitluskeskkond:

Kirjeldab ära keskkonna riistvaraliselt millel arendatud tarkvara toode toimima peab. See võib endas sisaldada erinevaid:

• Operatsioonisüsteemid
• Muud tarkvaralised platvormid
• Riistvara (olgu siis kas kliendipoolne või lõppkasutajapoolne)
• Serverid (kas virtuaalsed või füüsilised)
• Jälgimisvahendid
• Andmebaasid
• Ja muud
• Funktsionaalsete ja tehnilised nõuded:

Kirjeldab ära erinevad funktsionaalsed nõuded (näiteks sisselogimisfunktsioon backendis) kasutajalugudena ning muud tehnilised nõuded arenduskeskkonnas. Sisaldab ka endas erinevaid UML skeeme.

Arhitektuurse disaini dokument

Kujutab endast arendatava toote või süsteemi sisemist ülesehitust. Kirjeldab ära ka selles süsteemis esinevaid erinevaid mooduleid, komponente ning muid sõltuvusi. Pannakse kirja ka kuidas need komponendid/moodulid omavahel suhtlevad ning kuidas süsteem ise tervikuna suhtleb süsteemiväliste elementidega (muud liidesed/apid/platvormid/riistvarad/jne). Ära kirjeldatakse ka arhitektuur keskkonnale kus ja kuidas valminud toode (või selle süsteemi erinevad osad) hiljem olema peab(/peavad).

Dokumendi eesmärk on tekitada arenajale struktuur mida nad arendama hakkavad, see struktuur tuletatakse tarkvara nõuete dokumendist. Dokumendi koostab süsteemiarhitekt.

Mida arhitekstuurse disaini dokument sisaldama peab?

• Sissejuhatus:

Kirjeldatakse ära dokumendi eesmärk (milleks ja kuidas), viidatakse muudele dokumentidele (sealhulgas tarkvara nõuete dokument) ning omab sisukorda.

• Arendusvahendid ja arenduskeskkond:

Kirjutatakse välja milliseid arendusvahendeid on otsustatud arendustööks rakendada. Kirjeldatatakse ära ka nende seadistus ja põhjendatakse ära miks just need arendusvahendid valitud on. Kirjeldatakse samamoodi ära ka peale arendusvahendite arenduskeskkond.

• Arendusstandardid:

On kokkuleppelised konvensioonid mida kogu arndusmeeskond jälgima peab, nendeks on:

• Programmeerimisstandard - kas kirjutatakse koodis klassis erinevad moodulid, või tehakse igale funktsioonile oma klass näiteks
• Kommenteerimisstandard - Millises vormis ja kui palju koodi kommentaare kirjutatakse. Näiteks igal funktsioonil on oma summary (C#///) ning seal kirjutatakse funktsioonid lahti kindla keelelise süntaksiga, näiteks: "Given when function has parameter for ID, returns object from Database" (Antud näide on Given-When-Then süntaks)
• Nimetusstandard - Kuidas koodis kirjutatakse meetodite ja muutujate ning muude elementide nimetusi. Näiteks: Meetodi kirjutatakse nii, et mitmesõnalise meetodi iga sõna esimene täht on suur: "Addnumbers()" aga muutuja nimes on iga esimene sõna väikese tähega: "int numberFromUser = 0;". Antud jhul on meetodi näide "capital case" ja muutuja näide "camel case".
• Süsteemide vaheline suhtlemine:

Kirjeldatakse ära teised, välised süsteemid ja kuidas nendega arendatav tarkvaratoode suhtlema peaks. Sealhulgas ka mis kujul ja mis viisil need välised süsteemid infot vastu võtavad ja tagasi annavad.

• Sisemine struktuur:

Kirjeldatakse ära kuidas arendatav toode sisemiselt erinevateks komponentideks jaotub, ning milline on selle üleüldine sisemine struktuur. Mida iga komponent tegema peab, mis on selle komponendi eesmärk ja kuidas komponendid omavahel suhtlevad.

• Otsuste põhjendus:

Siin tuuakse välja miks miski arhitektuuriotsus langetati, ehk miks just nii mitte naa. Pakutakse välja ka olemaolevatele otsustele alternatiive juhuks kui esialgne plaan ei sobi või on tõkestatud. Tuuakse välja ka nõuded mille põhjal erinevad otsused langetati, ehk mida see otsus lahendama peaks.

• Jõudlusnõuded:

Pannakse kirja tarkvaratootele kliendi poolt esitatud jõudlusnõuded, näiteks: kui palju kasutajaid suudab sotsiaalmeedia platvorm suudab korraga hallata. Testimise käigus üritataksegi testida arendusjärgus olevat toodet simuleeritud koormusega. Kõik muud jõudlusnõuded peaksid olema ka testitavad sellisel viisil.

• Lõppkasutajaga suhtlemine:

Kuidas programm väljendab oma funktsionaalsust lõppkasutajale, ning millisel viisil esitatakse programmis tekkinud vigu *kasutajale*. Ehk teisisõnu on siin ka kasutajaliidese disain. Kasutajaliidese disain võib olla ka eraldi oma dokument.

• Toote ressursinõuded:

Kirjeldab ära kui palju vajab arendatav toode erinevaid süsteemi riistvara ressursse nagu:

• Mälu
• Andmebaasimahtu
• Võrgu ribalaiust
• Arvutusvõimsus
• Elektrit
• Turvalisuse tagamine:

Kuidas ja mis viisidel hoitakse lõppkasutaja andmed ja riistvara terve ja turvalisena ning tehakse kindlaks et lõppkasutaja saaks kätte ainult need andmed mida tal programmis oleva tegevuse teostamiseks vaja on. Näiteks krüpteeritakse tundlikud andmed andmebaasi esmasel sisestamisel ära, ning iga järgmine kord võrreldakse kasutaja sisestusi (nagu parool jms) andmebaasi juba oleva krüpteeritud kujuga.

• Porditavus:

Kas programm on võimalik käivitada teistel platvormidel (nii riistvara kui tarkvaralistel) platvormidel ja kui siis millistel.

Muudatuste tegemine

Kui klient otsustab et nüüd on tarkvaranõuete dokumendis mingi nõue vaja ringi teha, siis tuleb vastavad muudatused sisse viia ka arhitektuuri disaini dokumenti. Sellel eesmärgil on mõlemas dokumendis nõuete ja arhitektuurielementide vahel ristviited. Kui on vaja näiteks sisselogimisfunktsiooni muuta, et nüüd klient tahab ka saada telefoninumbrit 2FA läbiviimiseks, siis on seal nõude juures ka ristviide vastavale programmi moodulile, mis haldab kasutaja sisselogimist. Sellele kasutajaloole lisatakase juude telefoninumbri küsimine ja juurdelisatud osa läheb arendusse uue inkremendina. ning vastupidi, kui arhitektuuris tuleb välja, et telefoninumbri küsimine ei ole võimalik, siis on selles dokumendis vastav ristviide tarkvara nõudele ja seal defineeritakse nõue ringi, et telefoninumbrit kohe küsid ei saa, tehakse uus nõue mis lubab kasutajal selle telefoninumbri hiljem lisada.

Kasutajajuhend

On dokument mis aitab lõppkasutajal kasutada ning navigeeria valminud tootes. Ta kirjeldab ära kuidas erinevaid tegevusi sooritada Milleks seda programmi üldse kasutada saab, kuidas lahendada KKK ja muid võimalikke kasutaja tegevue tagajärjel tekkinud veaolekuid. Kasutaja juhend on kirjutatud selle põhjal mis on kasutajale näha ning saadaval aga mitte käsitledes programmi- siseseid detaile. Näiteks, monteerimisprogramm kirjeldab kasutajale kuidas muuta tööriist nähtavaks läbi "View > Window" menüü aga mitte seda, millist muutujat muuta vaja, et kuvada see aken koodis (bool isToolVisible = false; -> bool isToolVisible = true).

Haldusjuhend

Haldusjuhend on dokument mille koostavad arendajad oma arendatava toote kohta potensiaalselt arendusega mitte tegevale isikule aga kes on kliendi palgal valminud süteemi hooldamas. Dokument käsitleb:

• Installatsiooni - kuidas süsteem kliendi riistvarale paigaldada, mis vead võivad installatsiooni käigus tekkida ja kuidas neid lahendada.
• Andmesiiret - kuidas süsteemi siirata kliendi poolt antud andmd minimaalsete tõrgeteta, üritades lahendada erinevai ülemiekupuudusi. Näiteks andmebaasi migratsioonid.
• Hooldus - mis on tarkvaratootel vaja oma töö jätkuks ilma arendusmeeskonna toeta.
• Administreerimine - kuidas klient oma rakendus toimuvat jälgib ja kontrollib.
• Konfigureerimine - ümberseade võimalikeks teisteks kasutusjuhtudeks või ajutiseks skaleerimiseks (näiteks ajutisel vaja rohkem servereid muuta saadavaks, kuidas levitada andmed ja muu konfiguratsioon rohkematele serveritele kui hetkel trkvara toode kasautab.
• Ja kuidas viia sisse arendusmuudatusi peale arendustöö lõppu (näiteks arendus on lõppenud aga tulevikus saab uus arendus- meeskond infot siit, kuidas eelnevalt muudatusi tehti.

Projektihaldusdokumentatsioon

On omakorda dokumendiartefaktide kogum, mis käsitleb projekti haldamisega seotud dokumente, sh. ajakava planeerimist, arendusega seotud ressurside planeerimist, arendustöö hetkejärku jms.