Artikleid dokumenteerimisest (0)

Tallinna Transpordikool
Ragnar Järviste
Artikleid dokumenteerimisest
Tallinn
2013
Dokumentatsioon
Süsteemi nõuete dokument on nõuete kogumise ja analüüsi tegevuse väljundiks, ning sisaldab kasutajate ning huvipoolte vajadustest lähtuvat süsteemi omaduste ja piirangute kogumit. Toome näiteid nõuetest: funktsionaalne nõue on, et kasutaja saab süsteemi abil hallata klientide andmeid ja arveid, turvanõude näide on, et süsteemist peab saama andmeid kätte ainult selleks volitatud isik. Tehnoloogiline piirang on, et kasutaja peab saama süsteemiga suhelda veebilehitseja abil.
Süsteemi nõuete dokument peaks katma järgmised teemad:

• sissejuhatus: dokumendi eesmärk, projekti ulatus, kasutatavate terminite ja lühendite seletused (nn süsteemi sõnastik), viited teistele dokumentidele, dokumendi struktuuri kirjeldus;
  
• toote kirjeldus;
  
• kasutajate ja huvipoolte profiilid, eesmärgid, vajadused, kogemused. Kasutajate kirjeldamine aitab paremini mõista kasutajate vajadusi ning oskusi loodava tootega ümber käia;
  
• piirangud: kasutajatest või ümbritsevast keskkonnast lähtuvad piirangud, nt olemasolevate süsteemidega seostamine , arendusvahendid, õigusaktid;
  
• eeldused ja sõltuvused: toote loomine võib eeldada teatud tingimuste täitmist, nt et peatselt jõustatakse õigusakt; kolmas osapool loob liidestatava süsteemi;
  
• käitluskeskkond - kirjeldab platvormid, millel toode peab töötama, sh operatsioonisüsteemid, riistvaraplatvormid, andmebaasimootorid, veebiserverid, rakendusserverid, monitooringuliidesed jms;
  
• kõikide funktsionaalsete ja tehniliste (turva-, kasutatavus - jm) nõuete detailne kirjeldus, sh kasutuslood ja UML kasutuslooskeemid.
  

Nõuete dokumendi koostab analüütik koostöös tulevaste kasutajatega.
Arhitektuurse disaini dokument kirjeldab süsteemi ülesehitust, süsteemi komponente ning mooduleid, liideseid komponentide vahel ja liideseid teiste süsteemidega. Kirjeldatakse ka füüsiline arhitektuur - riistvara ja näidatakse, milline tarkvara komponent millisele riistvarale paigutatakse.
Arhitektuurse disaini dokument peaks katma järgmised teemad:

• sissejuhatus: dokumendi eesmärk, viited teistele dokumentidele, dokumendi struktuuri kirjeldus;
  
• arendusvahendite valiku ja häälestuse, arenduskeskkond;
  
• kodeerimise, sh kommenteerimise ja nimetamise standardid ;
  
• liidesed teiste süsteemidega, andmevahetusformaadid ja meetodid;
  
• toote sisemise struktuuri, ülesehituse: süsteemi jaotuse komponentideks, komponentide kohustused ja rollid, komponentide andmevahetus ;
  
• arhitektuuriotsuste tausta , alternatiivid, valikukriteeriumid;
  
• jõudlusnõuded. Väljendatakse viisil, mida on võimalik testimise käigus kontrollida;
  
• suhtlusviisid kasutajatega, vigade kuvamise viisid;
  
• ressursinõuded, st kui palju toode nõuab mälu, arvutusvõimsust jms;
  
• turvalisuse tagamise meetmed;
  
• porditavus, so võimalus käitada tarkvara erinevatel platvormidel.
  

Süsteemi nõuded ja arhitektuursed otsused peavad olema omavahel ristviidatud, st vajadusel on võimalik mingi nõude muutmisel muuta temaga seotud arhitektuurilisi lahendusi, ning vastupidi - mingi arhitektuuriotsuse muutmisel nt rahalistel põhjustel leida, milliseid nõudeid selline muutmisotsus puudutab.
Arhitektuurse disaini dokumendi koostab arhitekt lähtudes nõuete dokumendis toodud nõuetest.
Kasutajajuhend on dokument, milline käsitleb kasutaja vaadet süsteemile - milleks toodet saab kasutada, kuidas toodet kasutada, millised on võimalikud veasituatsioonid ning nende lahendamine. Kasutajajuhend ei vaatle süsteemi „sisemust" vaid seda, mis on kasutajale nähtav.
Projektidokumentatsioon käsitleb projektijuhtimisega seotud materjale.
Haldusjuhend käsitleb toote installeerimist, andmesiiret, toote hooldust ja administreerimist, konfigureerimist, muudatuste sisseviimise korda.
Kasutusjuhend ( user guide ) on tehniline dokument, mis peab pakkuma tuge konkreetse süsteemi kasutajatele. Mõistena kasutatakse ka sõna manuaal (manual). Ka parimast tarkvarast ei ole kasu, kui kasutaja ei oska teda kasutada. Kogu kasutaja dokumentatsiooni kuuluvad lisaks kasutusjuhendile hooldusjuhised, tööshoidmise juhend, õppematerjal ja teised materjalid-juhendid süsteemi spetsiifikast lähtudes.
Kasutusjuhendi peab süsteemile kaasa andma arendaja . Hea on, kui juhendi kirjutab tehniline kirjutaja (technical writer), kellel on sellise materjali kirjutamise kogemus, mitte aga programmeerija . Väikesemas firmas tavaliselt eraldi kirjutaja puudub ning seda tööd peab tegema haldur või mõni teine tehnilise personali liige.
Tavaliselt lisatakse kasutusjuhendisse ekraanipildid, mis lihtsustavad arusaamist. Kasutatav keel peab olema võimalikult lihtne ning sobima auditooriumile. Ei ole sobiv kasutada žargooni ning erimõisted tuleks lahti seletada.
Kasutusjuhend koosneb:

• pealkirjast ja autoriõiguste selgitusest
  
• eessõnast, mis annab soovitusi juhendi kasutamiseks ja sisukorrast
  
• juhendist (olulisemate) süsteemi funktsionaalsuste kasutamiseks
  
• veaselgituste (troubleshooting) osast, mis peaks hõlmama olulisemad probleemid ja nendega toimetuleku võimalused
  

Tihti lisandub ka korduma kippuvate küsimuste osa (FAQ), mida on kergem pidada ja vajaduse korral täiendada digitaalses vormis, kontaktandmed , viited lisamaterjalidele, sõnastik ja indeks.
Vaata näiteks GoogleEarthi kasutusjuhendit:
http://earth.google.com/support/bin/static.py?page=guide_toc.cs
Juhend ise peab andma juhiseid lõppkasutajale tema töö tegemiseks ning sisaldama:

• sisendite kirjeldust: millist informatsiooni ootab süsteem kasutajalt , milline peaks olema sisendi formaat ja väärtuste lubatud piirid, kuidas andmeid sisestada ( klaviatuur , andmefailid jms) jne
  
• väljundite kirjeldust: milline on väljundid, kuidas neid interpreteerida, samuti peaks juhend kirjeldama ebastandardset väljundit ehk nt veateateid ja nende tähendust jms
  
• funktsionaalsuste kirjeldust: kuidas süsteemi tegelikult tööle panna, kuidas toimida ühe või teise eesmärgi saavutamiseks.
  

Kasutusjuhend võib olla organiseeritud kolmel erineval viisil, mis on sobilikud erinevale auditooriumile ja erineva kogemusega kasutajale:

• Õppematerjal (tutorial) - tüüpiliste funktsioonide sammsammuline kirjeldus. See variant sobib algajale esmaseks tutvumiseks tarkvarasüsteemiga
  
• Temaatiliselt jagatud materjal - iga peatükk on pühendatud omaette teemale , sisaldab reeglina põhjalikumat funktsionaalsuste kirjeldust võrreldes õppematerjaliga ja seetõttu sobib edasijõudnumale kasutajale süsteemi uute võimaluste avastamiseks
  
• Tähestikulises järjekorras organiseeritud informatsioon - see on vajalik kogenud kasutajale kui teatmematerjal, et midagi meelde tuletada.
  

Et kasutusjuhendid on enamasti digitaalsed, siis aitab viimast rolli täita ka otsimisvõimalus.
Kasutusjuhendi üks olulisemaid tingimusi on aga see, et ta vastaks tegelikkusele. Tihti kipub ette tulema olukord, kus süsteemi esimesele versioonile on küll loodud juhend, kuid süsteemi täiendamisel jääb (ununeb?) juhend muutmata ja ebaadekvaatne juhend on päris parajaks segaduste allikaks. Tehniline dokumentatsioon (technical reference document ) on dokumentide kogum, mida kasutatakse tehniliste objektide konstrueerimisel või projekteerimisel, tootmisel (valmistamisel) ja kasutamisel . Tehniline dokumentatsioon sisaldab tarkvarasüsteemi tehnilist kirjeldust, sh dokumente, mis on tekkinud arendustegevuse käigus. Et erinevad arendusmetoodikad käsitlevad arenduse käigus toimuvat dokumenteerimist veidi erineval viisil, siis on raske anda ühest loetelu dokumentatsiooni osadest. Kitsamalt peetakse tehnilise dokumentatsiooni all silmas dokumente, mis on abiks süsteemi hooldamisel, töös ja ajakohasena hoidmisel (nt kuidas installeerida uuendusi). Dokument kirjeldab tarkvarasüsteemi ülesehitust (koodi ja muude failide loetelu). Võimalik on ka kommenteeritud lähtekood. Seega võib osa tehnilisest dokumentatsioonist paikneda tarkvara enda sees. Lisaks veel andmestruktuuride ja keerulisemate algoritmide kirjeldused, Dokumentatsioon võib sisaldada mitmeid jooniseid, mida saab näiteks esitada modelleerimiskeeles UML. Tehnilise dokumentatsiooni koostamisel võib olla abi spetsiaalsetest dokumendigeneraatoritest. Näiteks oskab selline generaator kokku korjata kõigi moodulis olevate funktsioonide päised ning päisele järgnevad kommentaarid ning moodustada sellest eraldi dokumendi. Ja ongi olemas dokumenteeritud ülevaade sellest, mida moodul sisaldab ja mida selles olevad funktsioonid teha oskavad. Süsteemi ülesehituse kirjeldusest on kasu nendele, kes süsteemist vigu otsima või muudatusi ning uusi funktsionaalsuseid lisama peavad. Organisatsioonis vajaminevat informatsiooni säilitatakse põhiliselt dokumentides (digitaalsel või paberlikul kujul), andmeid aga enamasti andmebaasides. Infot võib defineerida kui sõnumit, mis esineb dokumendi või audiovisuaalses vormis oleva kommunikatsioonina. Nagu igal sõnumil, on ka infol saatja ja vastuvõtja. Info ülesanne on mõjutada vastuvõtja hinnanguid või käitumist. Erinevalt andmetest on infol tähendus, olulisus ning eesmärk. Andmed muutuvad infoks, kui nende looja lisab neile tähenduse. Oluline on märkida, et IT aitab andmeid infoks muuta ja neile väärtust lisada. Samas ei aita IT kaasa konteksti loomisele (kategooriad, kalkulatsioonid , vorm) - selle loovad inimesed. Pea iga rakenduse juures on vaja mingil kujul dokumenteerida või mugavalt kättesaadavaks muuta süsteemi nõuded, ülesehitus ning selgitused kasutajale. Kui põhjalik osa kirjutatakse eraldi dokumendina ning kui palju on leitav koodi ja kasutajaliidese kaudu - see sõltub juba märgatavalt kasutatavast arendusmeetodist. Eraldi kirjutisena olevat dokumentatsiooni aitavad märkimisväärses osas asendada näitlikud prototüübid, sobivalt kommenteeritud kood ning kokkulepitud testid. Samas - mõnel puhul on selgitamiseks mugavam lugeda eraldi süstemaatiliselt kirja pandud dokumenti. Väiksema tarkvara esmase loomise ajal on enamik teabest mugavalt kättesaadav tegijate peades ning selge sihtmärgi puhul edeneb töö ka ilma eraldi nõudeid, struktuuri ja kasutajajuhendit kirja panemata. Ka väiksema rakenduse puhul kipub loomise käigus unustamisi ette tulema, kuid nendest saab enamasti üle ka esmaste katsetuste või kaaslasepoolse meeldetuletuse abil. Kui aga tegijaid on rohkem, nad ei suhtle pidevalt vahetult või rakenduse loomine/muutmine jääb pikema ajavahemiku sisse, siis mälu põhjal töötav arendus enam ei toimi. Uuesti rakenduse juurde pöördudes kulub märkimisväärne osa ajast olemasoleva meelde tuletamise peale ning mõnedki algselt kokku lepitud põhimõtted ja piirangud võivad kergesti tähelepanuta jääda kui neid eraldi kirja pandud ei ole. Koodi sobiva struktuuri ja lühikeste asjalike kommentaaride abiga võib rakenduse ülesehituse meelde tuletamine (vahel isegi kümnetes) kordades lihtsustuda. Võrdluseks - Java või . NETi standardteekides olevate tuhandete klasside ja kümnete tuhandete käskude seas on pärast mõningast tutvumist võimalik paketipuud kaudu sobiva kohani jõuda üldjuhul maksimaalselt paari minutiga, enamasti sekunditega. Või siis sama teed kaudu veenduda sobiva käsu puudumises. Kui aga on tegemist mitmetest osadest suhteliselt suvaliselt ühendatud sobivalt dokumenteerimata veebisüsteemiga, siis võib üksiku pealtnäha lihtsa vea leidmiseks ja kõrvaldamiseks kuluda päevi. Ehkki klasse on vaid paarkümmend ning kasutatavaid käsklusi kokku mitte üle paarisaja (teksti autori isiklik kogemus). Veel hullem, kui kood pole üldse mõistlikul kujul klassideks ega meetoditeks jaotatud. Sel juhul võib juba paari tuhande realine rakendus tunduda selline müsteerium, et lihtsam on sama tulemuse saavutamiseks rakendus uuesti kirjutada kui olemasolevat parandama hakata. Uuesti kirjutamine ei pruugi sugugi alati paha mõte olla ning seda ei tasu ka liialt karta . Peab ainult tundma ja kindel olema, et uuel kujul rakendus märgatavalt paremini hallatav ja edasi arendatav on. Küllalt sageli võib selline ümber tegemine otstarbekaks osutuda juhul, kui rakendus eelmise versiooniga võrreldes on kolm või rohkem korda suuremaks paisunud. Mõned arendajad püüavad sellist ümbertegemisvajadust vältida ning kohe algul luua põhjaliku struktuuriga arendusprojekti, kus igal osal ja koodilõigul on kindel koht. Sellisel juhul aga kipub tulemuseks olema ka näiteks lihtsa kalkulaatori puhul mitmeteistkümne kataloogi ning mitmekümne failiga projektipuu, kus rakendusespetsiifilist sisu on siiski vaid paari faili seest. Selline lähenemine võib mugav olla tarkvarafirmade puhul, kus suurte rakenduste struktuur on selgelt välja kujunenud ning meeskond oskab sobilikke lõike kergesti leida. Kui aga tegemist rakendusega, mille tegevusloogika saab kirjeldada paari ekraanitäie programmikoodiga, siis on lühikesel lahendusel oma võlu - eriti, kui selle koodiga peavad hiljem tegelema mitmesuguse taustaga programmeerijad eri arendusvahendite abil. Isegi siis on kompaktne kood vahel mugav, kui on teada, et paari aasta pärast tuleb see süsteemi kasvamise ning nõuete muutumise tõttu märgatavalt ümber teha.
Nõuded muutuvad, süsteemid muutuvad, koos nendega peab muutuma ka dokumentatsioon. Sest dokumentatsiooni puudumisest hullem on vigane dokumentatsioon. Samas kiirete muutuste ajal on eraldiseisva põhjaliku dokumentatsiooni värskena hoidmine mahukas ja keeruline ülesanne. Kergesti kipuvad tekkima kohad, kus eelnevalt paigas olnud seosed muutmise käigus kaduma lähevad. Kui tahta süsteemi ja dokumentatsiooni kooskõla säilitada, siis üheks mooduseks alustada muutuste sisseviimist dokumentatsioonis ning pidada järge kõigi osadega, mis muutustega seotud võiksid olla. Ning alles lõpuks viia muudatused sisse ka tegelikult töötavasse süsteemi.
Teiseks mooduseks on võimalikult suure osa dokumentatsiooni sidumine programmikoodiga. Sest nagu vahel öeldakse, ei valeta kood kunagi - ikka teeb masin seda, mis seal kirjas. Sel juhul automaattestidega määratakse kõigepealt uus vajalik funktsionaalsus - mis on omakorda nõuete kirjelduseks. Ning muudes kohtades on dokumentatsioon võimalikult koodi juurest genereeritavate automaatsete kommentaaridena - siis piisab hoolitsemisest, et koodis koha peal tehtavad muutused sealsamas meetodi päises korralikult kommenteeritud saaks - ülejäänu eest otsustab juba kommentaaride põhjal dokumentatsiooni koostav rakendus.