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 moodustavadgi 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
• Kasutaja juhend
• Projektihaldusdokumentatsioon
• Süsteemi haldusjuhend

Mis 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õppkasutajagan ning kliendiga. Arvestatakse mõlemi vajadusi
ning selgitatakse välja erinevad takistavad aspektid.

Dokumendi eesmärk on anda arendajale arhitektuurse disaini dokumendi 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 peaks

• Sissejuhatus
  

Kirjeldab ära dokumendi eesmärgi(Milleks ja kellele), Projekti ulatuse(Mida arendatakse, mida mitte)
Terminite sõnastik(Mittearendajatele kirjeldamakskasutatud tehnoloogilisi termineid), Viiteid teistele
Dokumentidele(erinevaid uml diagrammid, kasutajajuhendid, meeskonna arenduse halduskeskkond, projekti
juhtimise halduskeskkond, Arendatava töö enda haldusjuhend, spm)




• 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
Registreeritud kasutaja	Kõike mis külaline + Teha postitusi Laadida üles pilte Vaadata postitusi Saata teistele kasutajatele sõnumeid Kommenteerida postitusi
Admin	Kõike mida registreerinud 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 kasutaja rahulolu

Profiilide detailide bäljakirjutamine 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 arenduselette tulla, kasutajatel endal olla,
Keskonnast toode toimima peab, arendusvahenditest tulenevad piirangud ja seaduslikud piirangud



• Erinevad eeltingimused/ sõltuvused



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




• Käitumis keskkond:

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


• Operatsioonisüsteemid
• Muud tarkvaralised platvormid
• Riistvara (Olgu siis kas kliendi poolne või lõpkasutaja poolne)
• Serverid(olgu siis virtuaalsed või füüsilised)
• Jälgimisvahendid
• Andmebaasid
• Ja muud.


• Funktsionaalsete ja tehnilised bõuded:



Kirjeldab ära erinevad funktsionaalsed nõuded(Näiteks sisselogimisefunktsioon 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 süsteemiväliste elementidega (Muud liidesed/apid/platvormid/riistvarad/jne). Ära kirjeldatakse
ka arhitektuur keskkonnale kus ja kuidas valminud toode (Või 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 kiistab süsteemiarhitakt

Mida arhitektuurse disainin dokument endas sisaldab

• Sissejuhatus



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



• 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 ära samamoodi ka peale arendusvahendite
arenduskeskkond




• Arendusstandardid:



On kokkulepelised konventsioonid, mida kogi arendusmeeskond jälgima peab, nendeks on:

• Programeerimisstandard - Kas kirjutatakse koodis klassis erinevaid moodulid, või tehakse igal funktsioonil
  oma klass
• 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 nimetussi.
  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 muutujanä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 vastuvõtavad ja tagasi annavad




• Sisemine struktruur



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õhejndus



Siin tuuakse välja miks miski arhitektuuri otsus langetati, ehk miks just nii mitte naa. Pakutakse välja ka
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 oleam ka testitavad sellisel viisil


• Lõppkasutajaga suhtlemine

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



• Tootja ressursi nõudlus



Kirjeldab ära kui palju vajab arendatav toode erinevaid süsteemi raudvara nõudeid resursse nagu:


• Mälu
• Andmebaasimahtu
• Võrgu ribalaius
• 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 andmebbasi esmasel sisestamisel ä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 ka tarkvaralistel) platvormidel, ja kui
siis millistel

Muudatusete tegemine

Kui klient otsustab, et nüüd on vaja tarkvara 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 arhitektuurielemendi vahel ristviited
Kui on näiteks vaja sisselogimisfunktsiooni muuta, et nüüd klient tahab ka saada telefoninumbrit 2FA läbiviimiseks, siis on seal
nõude juures ka ristviide vastavale programi moodulile, mis haldab kasutaha sisselogomist. Sellele kasutajaajaloole 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 kasjutajal
Selle telefoninumbri hiljem lisada

kasutajajuhend

On dokument mis aitab lõppkasutajal kasutada ning navigeerida valminud tootes. ta kirjeldab ära kuidas erinevaid tegevusi soovitada
milleks seda programmi üldse kasutada saab, kuidas lahendada korduma kippuvaid küsimusi ja muid võimalikke kasutaja tegevuse tagajärjel
tellinud 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 näiteks 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 mille koostavad arendajad mille koostavad arendajad toote kohta potensiaalselt mittetegevale isikule, aga
kes on kliendi palgal valminud süsteemi hooldamas. Dokument käsitleb:

• Installatsiooni - kuidas süsteem raudvarale paigaldada, mis vead võivad installatsiooni käigus tekkida ja kuidas
  neid lahendada
• Andmesiirdet - kuidas süsteemi siirata kliendi poolt antud andmed minimaalsete tõrgeteta, üritades lahendada
  erinevat üleminuekupuudusi. Näiteks andmebaasi migratsioonid
• Hooldus - mis on tarkvaratootel vaja oma töö jätkuks ilma arendusmeekonna toeta
• Administreerimine - kuidas klient oma rakenduses toimuvat jälgib ja kontrollib
• Konfigureerimine - ümberaseadmine võimalikeks teisteks kasutusjuhtumiseteks või ajutiseks skaleerimiseks (Bäiteks ajutiselt vajab
  rohkem servereid muuta saadavaks, kuidas evitada andmed ja muu konfiguratsioon rohkematel serveritel kui hetkel tarkvara toode kasutab)
  
• Ja kuida sviia sisse arendusmuutusi 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 planeermist arendustöö hetkejärkujm