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 tegevusi ja nende tegijaid.
Dokumentatsioon tekib peaaegu igas tarkvaraarenduse elutsükli etapis ja pm igas tarkvaraarenduse elutsükli tüübis.
Need artefaktsid kokku moodustavadki tarkvara dokumentatsiooni.

Milliseid artefakte dokumentatsioonis esineda võib?

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

• süsteeeminõuete dokument
• arhitektuurse disaini dokument
• kasutajajuhend
• projektihaldusdokumentatsioon
• süsteemi haldusjuhend

mida need endast kujutavad ja 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.

Dokumendi eesmärk on anda arendajale arhitektuurise 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 peab?

• sissejuhatus:

Sissejuhatus kirjeldab ära dokumendi eesmärgi (milleks või kellele), projekti ulatsue (mida arendatakse, mida mitte),
terminite sõnastik mittearendajale kirjeldamaks tehnoloogilisi termineid, viiteid teistele dokumentidele
(erinevad UML diagrammid, kasutajajuhendid, meeskonna arenduse halduskeskkond, projektijuhtimise halduskeskkond,
arendatava töö enda haldusjuhend jpm).




• Tootekirjeldus:

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äitesks rollipõhine tabel:

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 mis registreeritud külastaja + 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äljakirjutamine aidab 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 eeltingumised/sõltuvused:

Toote loomist võib tingida mingisugune eelven tingimus- viiakse sisse riigi süsteemis mingisugune muudatus, digitaalne
vahend selle jaoks puudub ning leitakse, et on vaja arendadavastav tööriist, et tagada riigisüsteemi muudatuse ülelhoid.


• 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 kliendi- või lõppkasutajapoolne)
• serverid (virtuaalsed või füüsilised)
• jälgimisvahendid
• andmebaasid
• ja muud


• funktsionaalsed 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 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, platvormis, riistavrad jne).
Kirjeldatakse ka arhitektuur keskkonnale, kus ja kuidas valminud toode (või selle süsteemi erivevad osasd) hiljem olema peab.

Dokumendi eesmärk on tekitada arendajaile struktuur, mida nad arendama hakkavad. See struktuur tuletatakse tarkvaranõude dokumendist.
Dokumendi koostab süsteemi arhitekt.

Mida arhitektuurse disaini dokument endas sisaldama peab?

• sissejuhatus

Kirjeldatakse dokumendi eesmärk(milleks ja kuidas). Viidatakse muudele dokumentidele, sh tarkvaranõuete dokumendile
ning omab sisukorda.

• arendusvahendid ja arenduskekskond

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


• 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
• kommenteerimisstandard- millises vormis ja kui palju koodi kommentaare kirjutatakse, nt igal funktsioonil
  on oma summary (C#///) ning seal kirjutatakse funktsioonid lahti kindla keelelise sünkltaksiga, nt "Given when function
  has parameter for ID, then returns object from Database"


• nimetusstandard- kuidas koodis kirjutatakse meetodite ja muutujate ja muude elementide nimetusi, nt meetodid 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üsteemidevaheline suhtlemine:



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


• sisemine struktuur:



kirjeldadakse, 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,m ille põhjal erinevad otsused langetati ehk mida see otsus lahendama peaks.


• jõudlusnõuded:



pannakse kirja tarkvaratootele kliendi poolt esitatud jõudlusnõuded, nt kui palju kasutajaid suudab sotsaalmeediaplatvorm korraga hallata. Testimise käigus üritataksegi testida
arendusjärgus olevat toodet simuleeritud koormusega. Kõik muud jõudlusnõuded peaksid olevad ja testitavad sellisel viisil.


• lõppkasutajaga suhtlemine



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


• toote ressursinõuded:



Kirjeldab, kui palju vajab arendatav toode erinevaid süsteemi riistvara resursse nagu:


• mälu
• andmebaasimahtu
• võrgu ribalaiust
• arvutusvõimsust
• elekter


• 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, nt krüpteeritakse tundlikud andmed andmbaasi esmassel sisestusel ning iga järgmine kord võrreldakse
kasutaja sisestusi (nt parool jms) andmebaasis juba oleva krüpteeritud kujuga.


• porditavus:

Kas programmi on võimalik kasutada teistel (nii riist- kui tarkvaralistel) platvormidel ning kui, siis millistel.

Muudatuste tegemine

Kui klient otsustab, et nüüd on tarkvara nõuete dokumendis mingi nõue 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 nt sisselogimisfunktsiooni muuta, et klient soovib nüüd saada ka telefoni numbrit aFA läbiviimiseks, siis on seal
ka riristviide vastavale programmi moodulile, mis haldab kasutaja sisselogiumist. Sellele kasutajaleloole lisatakse juurde
telefoninumbri küsimine ja juurdelisatud osa läheb arendusse uue inkremendina. Ka vastupidi- kui arhitektuuris tuleb välja, et telefoninumbri
küsimine ei ole võimalik, siis on dokumendis ristviide tarkvaranõudele ja seal defineeritakse nõue ringi, et telefoninumbrit kohe
küsida ei saa, tehakse uus nõue, mis lubab kasutajal selle telefononinumbri hiljem lisada.

kasutajajuhend

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 KKK 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 programmisiseseid detaile, nt 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.
Näiteks bool isTooVisible = False; -> bool isTooVisible = 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 riistvarale paigutada, mis vead võivad installatsiooni käigus tekkida ning kuidas neid lahendada
• andmeseiret- kuidas süsteemi siirata kliendi poolt antud andmed minimaalsete tõrgeteta, üritades lahendada erinevaid üleminekupuudusi, nt 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, nt on vaja ajutiselt rohkem servereid muuta
  saadavaks, kuidas evitada andmed ja muu kkonfiguratsioon rohkematele serveritele kui hetkel tarkvaratoode kasutab.
• ja kuidas viia sisse arendusmuudatusi peale arendustöö lõppu, nt uue meeskonna poolt, st arendus on lõppenud, aga tulevikus saab uus
  arendusmeeskond infot siit, kuidas eelnevalt tehti.

Projektihaldusdokumentatsioon

on omakorda dokumentide ja artefaktide kogum, mis käsitleb projektihaldamisega seotud dokumente, sh ajakava planeerimist, arendusega seotus ressursside
planeerimist, arendustöö hetkejärku jms.