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 tehtuid 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 tõkendid.

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õuete 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 Registeerida kasutaja
Registreetitud kasutaja	Kõike mis külaline + Teha postitusi Laadida üles pilte Vaadata postitusi Saata teistele kasutajatele sõnumeid Kommenteerida postituste alla
Admin	Kõike mis registreerunud kasutaja + Kasutajaid bännida Postitusi kustutada Kommentaare eemaldada Pilte eemaldada
Süsteemi administraator	Hoolitseb veebiäpi toimimise eest, aldab 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 vaja teha 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üsteemist 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 tarkvaratoode toimima peab. See võib endas sisaldada erinevaid:


• Operatsioonisüsteemid
• Muud tarkvaralised platvormid
• Riistvara (olgu siis kas kliendipoolne või lõppkasutajapoolne)
• Serverid (Olgu 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 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 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
  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 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 juhul on meetodi
  näide "capital case" ja muutuja nä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 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 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 pooolt esitatud jõudlusnõuded, näiteks: kui palju kasutajaid suudab
sotsiaalmeedia platvorm korraga hallata. Tesitmise 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õimsust
• 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 ristliide vastavale programmi moodulile, mis haldab kasutaja sisse logimist. Sellele kasutajaloole lisatakse juurde
telefoninumbri küsimine ja juurdelisatud osa läheb arendusse uue inkremendina.
Vastupidiselt, kui arhitektuuris tuleb välja, et telefoninumbri küsimine ei ole võimalik, siis on selles dokumendis vastav ristviide
tarkvara nõudele ja sealt 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 on
  vaja rohkem servereid saadavale muuta saadavaks, kuidas evitada andmed ja muu konfiguratsioon rohkematele serveritele kui hetkel
  tarkvaratoode 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.)