Tagasi

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 tehtud tegevusi ja nende tegijaid. Dokumentatsioon tekib peaaegu igas tarkvaraarenduse elutsükli etapis ja põhimõtteliselt igas tarkvara- arenduse elutsükli tüübis. Need artefaktid kokku moodustavadki Tarkvara dokumentatsiooni.

Milliseid artefakte dokumentatsioonis esineda võib?

On olemas erinevaid tüüpe dokumentatsioone, aga tüüpiliselt esinevad vähemalt järgnevad:

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

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

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 takistavad aspektid.

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

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

• Sissejuhatus:

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

• Toote kirjeldus:

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

• Erinevate osapoolte profiilid:

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


Roll	Tegevused
Külaline	Vaadata pealehte Registreerida kasutaja
Registreerunud kasutaja	Kõike mis külaline + Teha postitusi Laadida üles pilte Vaadata postitusi Saata teistele kasutajatele sõnumeid Kommenteerida postituste all
Admin	Kõike mis registreerunud kasutaja + Kasutajaid bännida 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 arendajail aru saada mis tegevusi neil teha vaja on, et tagada vastav funktsionaalsus lõpptootes.
• Piirangud:

Kirjeldatakse ära erinevad piirangud või tõkestavad 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 tagada 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 (olgi siis 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 ülesehitus. Kirjeldab ära ka selles süüsteemis esinevaid erinevaid mooduleid, komponente ning muid sõltuvusi. Pannakse kirja ka kuidas need komponendid/moodulid omavahel suhtlevad ning 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 arendajaile struktuur mida nad arendama hakkavad, see struktuur tuletatakse tarkvara nõuete dokumendist. Dokumendi koostab süsteemiarhitekt.

Mida arhitektuurse disainin dokument endas sisaldama peab?

• Sissejuhatus:

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

• Arendusvahendid ja arenduskeskkond:

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

• Arendusstandardid:

On kokkuleppelised konventsioonid mida kogu arendusmeeskond 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, then 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 kirjutakse nii, et mitmwsõ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 juhul on meetodi näide "capital case" ja muutajanäide "camel case".
• Süsteemidevaheline 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 kompentideks jaotub, ning milline on selle üleüldine sismeine 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 olemasolevatele 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 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 raudvara ressursse nagu:

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

Kuidas ja mis viisidel hoitakse lõppkasutaja andmed ja raudvara 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 sisestusel ära, ning iga järgmine kord võrreldakse kasutaja sisestusi (nagu parool jms) andmebaasis juba oleva krüpteeritud kujuga.

• Porditavus:

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

Muudatuste tegemine

Kui klient otsustab, et nüüd on tarkvara nõuete dokumendis mingi nõue vaja ringi teha, siis tuleb vastavad muudatused sisse viia ka arhitektuurse disaini dokumenti. Sellel eesmärgil on mõlemis 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 lisatakse juurde 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üsida ei saa, tehakse uus nõue mis lubab kasutajal selle telefoninumbri hiljem lisada.

Kasutajajuhend

On dokument mis aitab lõppkasutajal kasutada ning navigeerida valminud tootes. Ta kirjeldab ära kuidas erinevaid tegevusi sooritada, milleks seda programmi üldse kasutada saab, kuidas lahendada Korduma Kippuvaid Küsimusi ja muid võimalikke kasutaja tegevuse tagajärjel tekkinud veaolekuid. Kasutajajuhend 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 mittetegelevale isikule, aga kes on kliendi palgal valminud süsteemi hooldamas. Dokument käsitleb:

• Installatsiooni - kuidas süsteem kliendi raudvarale paigaldada, mis vead võivad installatsiooni käigus tekkida ja kuidas neid lahendada
• Andmesiiret - kuidas süsteemi siirata kliendi poolt antud andmed minimaalsete tõrgeteta, üritades lahendada erinevaid üleminekupuudusi. Näiteks andmebaasi migratsioonid.
• Hooldus - Mis on tarkvaratootel vaja oma töö jätkuks ilma arendusmeeskonna toeta.
• Administreerimine - kuidas klient oma rakenduses toimuvat jälgib ja kontrollib.
• Konfigureerimine - ümberseade võimalikeks teisteks kasutusjuhtumiteks, või ajutiseks skaleerimiseks (Näiteks ajutiselt vaja rohkem servereid muuta saadavaks, kuidas evitada andmed ja muu konfiguratsioon rohkematele serveritele kui hetkel tarkvara toode kasutab).
• Ja kuidas viia sisse arendusmuudatusi peale arendustöö lõppu (Näiteks arendus on lõppenud, aga tulevikus saab uus arendusmeeskond infot siit, kuidas eelnevalt muudatusi tehti).

Projektihaldusdokumentatsioon

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