Mis on dokumentatsioon?

Tarkvara arenduse elutsüklis on olemas erinevaid tegevusi, nende tegevuste tulemusel tekib hulk artifakte
mis dokuminteerib nendes tegevustes kas siis tehtavaid tegevusi või tehtud tegevusi ja nende tegijaid.
Dokumentatsioonis tekib peaaegu igas tarkvaraarenduse elutsükli etapis ja põhimõtteliselt igas tarkvara-
arenduse elutsükli tüübis. Need aretefaktid kokku moodustavadki Tarkvara dokumentatsiooni.

Millised artefakte dokumentatsioonis esineda võib?

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

• Süsteemi nõute dokumentatsioon?
• Arhitektuurse disaini dokument
• Kasutajajuhend
• Projektihaldusdokumentatsioon
• Süsteemi haldusjuhend

Mida need endast kujutuvad 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õlema vajadusi
ning selgitatakse välja erinevad tõkendid.

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

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

• Sissejuhatus:

Kirjeldab ära dokumendi eesmärgi (Milleks ja kellele), Projekti ülatuse (Mida arendatakse, mida ette),
Terminite sõnastik(Mittearendajaile kirjeldamaks kasutatud tehnoloogilisi termineid), Viited 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
Registreerenud 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 toimise eest, haaldab andmebaase, teeb korrastustöid, vajadusel konfigureerib, ja jälgib muud statistikat et tagada kliendi ja kasutajate rahuolu.

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 muudatud, digitaalne
vahend selle jaoks puudub, ning leitakse et on vaja arendada vastav töörist et tagada riigisüsteemi muudatuse ülahoid




• Käitluskeskkond:



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


• Operatsioonisüsteemid
• Muud tarkvaralised platvormid
• Riistvara (olgu siis kas kliendipoolne võo lõppkasutajapoolne)
• Serverid (olgu siis kas virtuaalsed või füüsilised)
• Jälgimisvahendid
• Andmebaasid
• ja muud.


• Funktsionaalsete ja tehnilised nõuded:



Kirledab ä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 ülesehitus. Kirjeldab ära ka selles süsteemis 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 disaini 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 millised arendusvahndeid 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:

• Programmeerimisstandart - 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 parametr 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: Metoodi kirjutakse 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 juhul on metodi
  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 sisemine struktuur. Mida iga komponent tegema peab, mis on selle komponendi eesmärk
ja kuidas komponendit 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. Tesimise käigus üritaksegi 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õppkasdutajatele, ning millisel viisil esitatakse programmis
tekkinud vigu *kasutajale*. Ehk tõsisõnu on siin ka 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 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õomalik 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 inkremeedina.
Ning vastupidi, kui arhitektuuris tuleb välja, et telefoninumbrit kohe küsida ei ole võimalik, siis om selles dokumendis vastav riistviide
tarkvara nõudele, ja seal defineeritkase 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üsimisu 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ähtvaks 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
  üleminekuupuudusi. 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õimaliseks teisteks kasutusjuhtumiseks, 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 (Npteks arendus on lõppenud, aga tulevikus saab uus arendusmees-
  kond 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.