SÜSTEEMIARENDUSE PROTSESS JA MEETODID

Tarkvara ja süsteemi testimine

Toote kvaliteet sõltub eelkõige toote valmistamise protsessi (tarkvara korral seega tarkvara arendusprotsessi) kvaliteedist ning toote arendajate-valmistajate (analüütikute, arhitektide, programmeerijate, projektijuhtide jt) teadmistest, oskustest ning motivatsioonist. Seega tarkvara kvaliteedi tõstmise viisideks on protsesside parendamine, inimeste koolitamine jms. Tarkvara on vaja ka kontrollida vigade suhtes ehk testida.

Testimine on kasutusel mitmetes inimtegevuse valdkondades: teaduses testitakse vaatluste ja eksperimentidega hüpoteese ning teooriaid, õppe läbiviimisel testitakse tudengeid, tootmises testitakse toodangut.

Testimise eesmärgiks on näidata, et tarkvara teeb seda, mis vaja ja avastada programmis vigu enne, kui see kasutusse antakse. Testimiseks tavaliselt käivitatakse tarkvara kasutades testandmeid. Edasi kontrollitakse testi tulemusi vigade ja anomaaliate leidmiseks või ka mittefunktsionaalsete omaduste kontrollimiseks. Testimise abil saab leida vigu, kuid mitte tõestada nende puudumist. Testimine on üks osa suuremast valideerimise ja verifitseerimise protsessist.

Tüüpilist testimisprotsessi kujutab järgmine joonis:

Joonis 1.6. Testimise protsess [5]

Testjuhtumitele vastavalt valitakse testandmed (sisend) ja lisaks fikseeritakse, milline peab selliste andmete korral olema süsteemi käitumine või väljund. Süsteem käivitatakse valitud testandmetega ja tulemust võrreldakse oodatava tulemuse/käitumisega. Kui süsteem käitus oodatult, loetakse test läbituks. Kui mitte, siis on avastatud viga. Testi tulemuse registreerimiseks koostatakse aruanne. Milles viga täpsemalt seisneb, peavad välja selgitama arendajad ja selle siis parandama.

Tarkvara ja süsteemi ehk toote testimine on otseselt seotud toote kvaliteediga. Toode on kvaliteetne, kui ta rahuldab oma tööga vajadusi, millised motiveerisid toodet looma. Seega on vajalik vastavate testide läbiviimine tegemaks kindlaks, kas toode vastab täielikult kliendi nõuetele. Siiski, absoluutse kindluse, et toode ei sisalda vigu, saavutamine ei ole reaalsuses võimalik.

Testimise eesmärgid

Eelnevat kokkuvõttes võib öelda, et testimisel on kaks suuremat eesmärki:

1. Näidata arendajale ja kliendile, et tarkvara vastab talle püstitatud nõuetele. Kliendi seisukohast tähendab see, et iga tema poolt soovitud ja nõuete dokumendis kirjas oleva funktsionaalsuse jaoks on läbi viidud vähemalt üks test (reeglina muidugi rohkem). Üldkasutatava tarkvara puhul aga seda, et testitud on kõiki tarkvaras ettenähtud põhiomadusi. Sellele eesmärgile vastavat testimist nimetatakse valideerimiseks. Edukas valideerimistest näitab, et süsteem töötab nii nagu vaja.
2. Leida olukordi, kus tarkvara käitub vigaselt, ebasoovitavalt või ei vasta spetsifikatsioonile. Vigade otsimine on seega mõeldud selleks, et likvideerida süsteemist mittesoovitud käitumine, nagu näiteks kokku kukkumised, mittesoovitud interaktsioonid teiste süsteemidega, vigased arvutused või rikutud andmed. Seda eesmärki täitvat testimist nimetatakse vigade testimiseks (defect testing). Siin on edukas test selline, mis näitab süsteemi vigast funktsioneerimist ehk teisisõnu leiab süsteemist vea (mida siis edasi parandama asutakse).

Testimise tüübid

Pragmaatiliselt oodatakse tarkvaratootelt usaldusväärsust, st et tarkvara funktsioneerib soovitud viisil etteantud tingimustel. Funktsioneerimise viis ja opereerimise tingimused on vaja püstitada toote arenduse esimestel etappidel ning täpsustada kogu arendustsükli käigus. Praktikas on võimatu testida kõikvõimalike sisendparameetrite kombinatsioonidega ning võrrelda tarkvara väljundit oodatava väljundiga. Seega on väga oluline valida efektiivne komplekt testandmeid kombineerituna testimise tüüpidega. Tänapäeval on kasutusel ka automaattestid. Kõiki teste, näiteks kasutuskõlblikkuse teste, ei ole võimalik automatiseerida.

Testimise olemuseks on kontrolltegevused, et näidata kõikide tarkvarale esitatud nõuete täidetust. Samuti peab testimisel veenduma, et kõik parandamiseks esitatud defektid ka parandatud saavad ning parandused ei põhjustaks omakorda uusi vigu.

Kuna tarkvaratoote kvaliteet oleneb suures osas läbiviidavate testide tüübist, tuleb neid hoolikalt valida ja toote tellijaga kokku leppida. Osa testimist teeb programmeerija, osa testimist testijad ning lõpuks rakendatakse ka kliente-tellijaid. Järgnevalt lühike ülevaade erinevatest testimise tüüpidest.

• Moodultestimise korral testitakse konkreetset tarkvaramoodulit - ühte alamsüsteemi kogu süsteemist. Testimist viib üldjuhul läbi moodulit realiseeriv arendaja. Moodulit tuleb kindlasti testida enne, kui moodul integreeritakse ülejäänud süsteemi. Mooduli testimisel tuleb jälgida, et moodul vastaks analüüsis püstitatud nõuetele. Mooduli testimise eesmärgiks on siiski vigade leidmine, mitte kasutajanõuetele vastavuse tõestamine. Näiteks kas moodulisse lisatud funktsioonid töötavad korrektselt ning tagastavad õigeid vastuseid. Mooduleid testitakse andmetepõhiselt: õigete, puudulike ja vigaste andmetega. Tüüpiliselt on siin tegemist nn „valge kast" testimisega, st testija tunneb testitava tarkvara sisemist ülesehitust ja tööloogikat.
• Integratsioontestimise korral testitakse moodulitevahelist koostööd - kontrollitakse, kas kokku pandud moodulid töötavad omavahel ja kas iseseisvalt vigadeta töötanud moodulid koos vigasid ei genereeri. Testijana kasutatakse üldjuhul sõltumatut testijat, st testijat, kes ise ei arendanud testitavaid mooduleid. Näide integratsioonitestist on igaöine kompileerimine, et kontrollida arendatava toote käivitatavust.
• Süsteemtestimise korral testitakse süsteemi kui terviku töötamist. Süsteemi testimisel musta kasti meetodil vaadeldakse süsteemi kasutajale nähtavaid osi (kasutajaliidest), süvenemata koodi (siit nimetus „must kast"). Testjuhtumid koostab testija (peamiselt kasutuslugude põhjal), kes testid ka läbi viib. Testijaid peab olema nii tellija kui täitja poolel. Seda laadi testimist nimetatakse ka funktsionaalsuse testimiseks.
• Regressioontestimine on igat tüüpi tarkvara testimine, mida kasutatakse peale koodi/süsteemi viidud muudatusi. Näiteks uue funktsionaalsuse lisamisel, konfiguratsiooni muutmisel, paikamisel. Regressioontestimise eesmärk on veenduda, et muudatused ja veaparandused pole tekitanud süsteemi uusi vigu. Testitakse muudetud mooduleid (moodultestimine) ja nendega seotud mooduleid ning kogu süsteemi funktsionaalsust (funktsionaalsuse testimine). Peamiseks meetodiks on juba kasutatud testide taaskäivitamine veendumaks, et süsteem toimib, vanad vead ei avaldu uuesti ja ei ole tekkinud uusi. Regressioontestimist on kasulik automatiseerida üldise töökoormuse vähendamiseks.
• Jõudlus- ja koormustestid on ette nähtud süsteemi tehniliste nõuetele vastavuse läbiproovimiseks. Jõudlustesti on võimalik läbi viia mitmel moel - iga komponendi jõudlust eraldi mõõtes või suure hulga testandmetega süsteemi tavakasutamist katsetades. Jõudlustesti eesmärk on tuvastada kriitilisemad kohad, kus võib tekkida ülekoormus ja kulutada aeg nende kohtade optimeerimiseks. Kui tavaliselt mõeldakse testandmed korralikult läbi ning valitakse sisendid eesmärgist lähtudes, siis selle testimisel puhul on võimalik testida ka juhusliku, arvuti poolt genereeritud suure andmehulgaga.
• Valideerimise eesmärk on kinnitada, et tarkvara töö tulemid väljatöötatud kujul sobivad määratud kasutamiseks. "Kas me teeme õiget tarkvarasüsteemi?"
• Verifitseerimise eesmärk on kinnitada, et protsessi või projekti iga tulem vastab spetsifitseeritud nõuetele. "Kas me teeme tarkvarasüsteemi õigesti?"
• Kasutatavuse testid hindavad süsteemi kasutusmugavust kasutaja vaatenurgast: Kasutatavuse testi eesmärk on avastada vigu ja kohti, mida paremaks võiks teha, selleks jälgitakse inimesi toodet kasutamas. Kindlasti ei saa kasutatavuse testimiseks pidada seda, kui kliendile näidatakse tulevase toote prototüüpi / pilti ja küsitakse, kas on arusaadav. Testimiseks peab inimene täitma konkreetseid ülesandeid ja sel teel selguvad tarkvarasüsteemis või ka veebilehel halvasti arusaadavad kohad. Kasutatavuse testimiseks sobivad nö "inimesed tänavalt", kes süsteemi esimest korda näevad. Aga ka eksperdid, kes oskavad kogemustest ja teooriatest lähtuvalt leida kasutusmugavuses nõrku kohti.
• Vastuvõtutest ehk aktsepteerimistest on kliendi poolt läbiviidav test valminud toote hindamiseks ja vastuvõtmiseks. Vastuvõtutesti testijuhtumid kirjeldavad üheselt projekti üleandmise ja vastuvõtmise kriteeriumid ning testijuhtumid peavad olema konkreetsed ja mõõdetavad ning nendes lepivad tellija ja teostaja projekti realiseerimise eel kokku;
• Koodi läbivaatus - erinevalt eelnevalt käsitletud testi tüüpidest, koodi läbivaatuse puhul koodi ei käivitata vaid koodi inspekteeritakse testija poolt. Läbivaatus eeldab küsimustiku olemasolu, mille alusel koodi hinnata ning sealt vigu otsida, mis tavatingimustes testides ei pruugi avalduda. Läbivaatajad peavad olema väga kompetentsed ka näiteks kasutatava keele osas. Mida otsitakse? Näiteks algväärtustamata muutujaid, ebasobivalt valitud andmetüüpe, muutujate või massiiviindeksite väljumist lubatud piiridest, tehete järjekorda, erinevate muutujatüüpide kokkusobivust jne.

Eelnimetatud tehnikaid tuleb kombineerida. Testitavaid omadusi on terve hulk, silmas tuleb pidada seda, et testimiseks on vaja, et toote nõuete püstitamise etapis vastava omaduse kohta ka nõuded püstitati ning püstitati viisil, mis võimaldab toote nõuetele vastavust kontrollida ehk mõõta. Loetleme allpoolt olulisemad nõuded tarkvara omadustele:

• funktsionaalsus - toote omadus väljendamaks tema sobivust seatud ülesannete täitmiseks, st tarkvaraga saab teha seda, mida klient vajab;
• turvalisus - toote omadus piirata äriloogikale/andmetele ligipääsu autoriseerimata isikute poolt;
• tõrkekindlus - toote omadus väljendamaks võimet tagada teatud jõudluse ja funktsionaalsuse tase veaolukorra tekke või liidese väärkasutamise puhul;
• taastuvus - toote omadus väljendamaks võimet taastada normaalne töörežiim ja jõudlus peale veaolukorra tekkimist;
• taastatavus - toote omadus väljendamaks keerukust ja vajaminevat töö hulka ning aega süsteemi põhifunktsionaalsuse taastamiseks avariiolukorra puhul;
• efektiivsus, jõudlus - toote omadus väljendamaks reageerimisele ja andmete töötlemisele kuluvat aega koormuse all;
• kasutatavus
  • mõistetavus - toote omadus väljendamaks vajaminevat aja hulka, mille jooksul kasutajad mõistavad süsteemi loogilist kontseptsiooni ja rakendatavust;
  • õpitavus - toote omadus väljendamaks vajaminevat aja hulka, mille jooksul kasutajad suudavad süsteemi kasutama õppida (näiteks andmete sisestamine/väljastamine jne);
  • kohaldatavus - toote omadus väljendamaks süsteemi paindlikust ja lõppkasutaja poolt enda jaoks sobivaks muutmise keerukust;
  • atraktiivsus - toote omadus väljendamaks lõppkasutajate rahulolu toote poolt pakutavate teenuste, esitluse ja käitumisega;
• stabiilsus - toote omadus väljendamaks muudatustejärgsete ootamatute nähtuste tekkimise riski suurust;
• taaskasutatavus - toote omadus väljendamaks toote osade taaskasutamise võimalusi teistes tarkvaraprojektides;
• porditavus - toote omadus väljendamaks aja- ja töökulu toote kohaldamisel teistesse keskkondadesse, platvormidele.

Erinevate testi tüüpide ja arendusetappide vastavust illustreerib alljärgnev joonis. Pidevad nooled näitavad tarkvaratoote arendusprotsessi sammude ajalist kulgu, punktiirjooned seoseid testi tüüpide ja arendusetappide vahel: nt moodultest kontrollib valminud mooduli vastavust mooduli spetsifikatsiooniga, milline sünnib detailse projekteerimise sammus; süsteemitest vastab tarkvara nõuete püstitamise sammule ning vastab küsimusele, kas valminud süsteem tervikuna täidab püstitatud nõudeid. Vastuvõtutest vastab küsimusele, kas tarkvaratoode vastab kliendi vajadustele, ehk kas toode on küps kasutuselevõtuks ja/või müüki paiskamiseks. [5]

Joonis 1.7. Tarkvaratoote testimise V-mudel. Mudel on osaliselt inspireeritud koskmudelist. [5]

Testimise käigus leitud vead tuleb dokumenteerida. Dokumenteerimine ei tähenda tingimata paberdokumendi vormistamist, pigem kasutatakse spetsiaalseid CASE-vahendeid, nt Mantis ja Bugzilla, mis abiks ka vearaportite edastamisel programmeerijatele.

Toote kvaliteediga on - lisaks testimisele - seotud ka ülevaatused. Ülevaatus on tegevus, milline viiakse tavaliselt läbi rühmatööna. Ülevaatuste käigus arutatakse ja hinnatakse tarkvaratoote projekti staatust, riske, tehakse otsustusi ressursside juhtimise ning toote nõuete-lahenduste vallast. Otsused peaks protokollima, määrates isikud, kes vastutavad otsuste tähtajalise elluviimise eest.

Ülevaatuste eriliigid on:

• tehnilised koosolekud, millistel osalevad toote arhitektid, analüütikud, projektid, kliendid. Analüüsitakse ja tehakse toote ülesehitust puudutavaid otsuseid;
• koodi läbivaatused;
• auditid, mida üldjuhul viivad läbi sõltumatud, välise organisatsiooni esindajad. Hinnatakse muuhulgas toote ja/või arendusprotsessi vastavust nõuetele, standarditele, formaalsetele protseduuridele, lepingutele jm. Maailmas tuntuim IT-audiitorite organisatsioon on ISACA (http://www.isaca.org), kelle poolt sertifitseeritud audiitorid kannavad CISA-tiitlit (Certified Information System Auditor - sertifitseeritud infosüsteemide audiitor).

Tarkvarasüsteemi juurutamine

Testitud tarkvaratoode tuleb võtta kasutusele. Süsteemi kasutusele võtt hõlmab kogu tarkvaraprotsessist juurutuse, andmeülekande vanast süsteemist, kasutajate ja süsteemi administraatorite koolituse, toe süsteemi kasutajatele ja paranduste sisseviimise juurutusjärgselt ilmnenud vigade parandamiseks.

Tarkvaratoote kasutusele võtt sisaldab mitmeid erinevaid samme. Puudub täpne protsess, sest situatsioon, kus tarkvara juurutatakse, varieerub erinevate klientide juures oluliselt. Siiski järgmised tegevused on reeglina vajalikud:

• tarkvaratoote levitamine, st installeerimine riistvarale. Keerukamate, hajutatud süsteemide on abiks UML levitusskeemid millised kirjeldavad tarkvara paiknemist erinevatel riistvara sõlmedes, sealhulgas:
  • Avalikustamine (release). Avalikustamine järgneb arendusprotsessile. See sisaldab kõiki tegevusi, et süsteem ette valmistada assembleerimiseks (masinkoodi viimiseks) ning kliendi juurde üleviimiseks. Selle tegevuse käigus määratakse ka ressursid, mis on vajalikud töötamiseks kliendi poolel.
  • Tarkvara installeerimine ja aktiveerimine- käivituvad komponendid paigutatakse arvutitele-serveritele, kus nad edasipidi töötama peavad. Keerulisemad süsteemid vajavad lisaks ka muu toetava tarkvara installeerimist (nt andmebaasimootori uus versioon jms). Tihti installeeritakse suurem süsteem mitmesse keskkonda - näiteks lisaks ka testserverile, mida saab hiljem kasutajakoolituseks ja muudeks katsetusteks kasutada.
  • Kohandamine ja uuendamine - uuendamise käigus installeeritakse uus versiooni süsteemist, kohandamine on samuti süsteemi muutmine, kuid põhjuseks on peamiselt muudatuse kliendipoolses keskkonnas.
• andmeülekanne vanast süsteemist - varem kasutatud süsteemis on reeglina andmed, mida tuleb ka edaspidi kasutada. Soovitav on automaatülekandevahendi loomine, milline käivitatakse ühekordselt andmete ülekandeks vanast süsteemist uude. Ülekandemehhanism võib olla päris keerukas, eriti kui vana süsteemi ja uue süsteemi andmestruktuurid on oluliselt erinevad. Kui andmete kogus on väike ja/või automaatteisenduse algoritmi väljatöötamine liigselt keerukas, on võimalik andmeid ka käsitsi üle kanda. Sellisel juhul võib olla vajalik luua raportid vanast süsteemist andmete väljavõtmiseks ja sisestusvormid vm vahendid andmete käsitsi sisestamiseks kasutuselevõetavasse süsteemi;
• muudatuste tegemine teistesse rakendustesse, millised peavad töötama koos ja/või kasutatakse koos arendatava tarkvaratootega;
• koolituse ettevalmistamine ja läbiviimine tarkvaratootega kokkupuutuvatele inimestele, sh järgmistele rollidele:
  • igapäevased kasutajad
  • administraatorid
  • kasutajatoe pakkujad.
  Koolitus peab hõlmama nii teoreetilist kui praktilist osa. Praktilist osa on soovitav läbi viia testimiseks ja/või koolituseks loodud keskkonnas (nii tarkvara kui andmed), seda eelkõige ennetamaks riske reaalsete andmete konfidentsiaalsuse, käideldavuse või tervikluse huvides.
• valmisoleku loomine kriisiolukorra juhtimiseks ja kriisiolukorras käitumiseks. Võimalikud kriisid tarkvaratoote kasutusele võtul on:
  • programmi mittetoimimine töökeskkonnas
  • vigade avastamine programmis
  • andmete kadu.

Viga tarkvaratootes võib tuua kaasa äriprotsesside katkemise ja suure majandusliku ning renomee kahju äriettevõttele või avaliku sektori asutusele. Kriisiolukorraks ettevalmistamise käigus lepitakse kokku rollid, protsessid ja juhtimise, kuidas kriisiolukorras käituda, kuidas suhelda kasutajate ja kriisireguleerijatega, kas ja kuidas teavitada avalikkust, kuidas vajadusel ja võimalusel võtta vana tarkvaratoode kasutusele jms.

Tarkvara kasutuselvõtu riskiks on ka inimesed. Eriti võib see avalduda tarkvara esmakordsel juurutamisel, kus võib tekkida suur vastuseis. Osa sellest riskist saab maandada eelpool mainitud koolituste abil. Lisaks on vajalik läbi mõelda igapäevased protseduurid. Kas seni kasutusel olnud protseduurid saavad samal viisil toimida nüüd, kui kasutusel tarkvarasüsteem? Tihtipeale ei saa. See võib põhjustada suurt inimlikku segadust ning lisada vastasseisu uuendustele. Seega lisaks tehnilistele õpetustele tarkvarasüsteemi kasutamise osas tuleb õpetada töötajaid läbimõeldult nö uut moodi asju ajama.

Näiteks kuidas peaks peale digitaalse dokumendihaldussüsteemi kasutuselevõttu käituma arvega, et see raamatupidaja poolt ülekantud saaks? Või kuidas saab õpilane peale uue õppeinfosüsteemi kasutuselevõttu teada järeleksamitest, mida enam seinale ei riputata?. Üldisemalt öeldes võib olla tarkvara kasutuselevõtmisel vajalik äriprotsesside ümberkujundamine, millel on kaks poolt - äriprotsesside kohandamine, mis esindab organisatsioonilist vaadet ning vastuvõtt ja heakskiitmine, mis esindab üksikisiku vaadet.

Juurutusetapi läbimiseks pakub Capers Jones oma raamatus Software Engineering Best Practices välja järgmised head tavad (best practices):

• Ühine sama rakenduse kasutajate võrgustikuga (kui selline on olemas)
• Küsi praegustelt tarkvarakasutajatelt nõu ja soovitusi tarkvara juurutamiseks.
• Leia konsultandid, kellel on juurutamiskogemus.
• Muretse tarkvara sobilike erikursuste loomiseks ning leia sobivad kursused
• Kohanda tarkvara kohalikeks vajadusteks.
• Tekita liides arendatava uue tarkvara ja väljavahetatava tarkvara vahele.
• Registreeri ja teavita vigadest ning defektidest, mis juurutamise jooksul ilmnevad.
• Installeeri tarkvaratootja paigad ja uuendused.
• Hinda uue rakenduse edukust.

Sama autori järgi võib juurutusetapp olla väga pikk isegi 12 kuud, nõuda mitmekümne inimese tööd ning ca 1 miljon $ raha. Tarkvara, mis ei ole otse antud firmale loodud, võib vajada ka päris pikka ja põhjalikku kohandamist, et seda saaks üldse kasutada.

Eelnevalt kirjeldatud tarkvaratoote juurutamine on pigem ühekordne tegevus. Vastavalt tarkvaraelutsükli mudelitele järgneb hoolduse faas, mis sisuliselt kestab seni, kuni tarkvara kasutuses püsib.

Seoses muudatustega ärikeskkonnas, seadusandluses, äri toimimises on vajadus tarkvaratoodet kaasajastada, samuti nõuavad tarkvaratootes avastatud vead parandamist. Tarkvaratoote muudatuste halduse aitab läbi viia kokkulepitud kord ja ka spetsiaalsed CASE-vahendid, millised võimaldavad teavitada vigadest tootest või muudatusvajadustest; muudatusnõudeid prioritiseerida olulisuse, kriitilisuse jm alustel, muudatuste realiseerimist täitmiseks suunata, hallata tarkvaraversioone jm.

Ka suuremate muudatuste sisseviimisega tarkvarasse (nt uute funktsionaalsuste lisamisega) kaasnevad vähemalt osaliselt eespool kirjeldatud juurutusetapid.

Kasutusjuhend ja tehnilised juhendid

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.