Važnost kvalitetne softverske dokumentacije

Softverska dokumentacija može se objasnit kao cijeli set dokumenata koji opisuje softverski proizvod
i sve dokumente proizvedene tijekom procesa razvoja softvera. Tipični primjeri su dokumenti za
korisničkim zahtjevima, dokumenti sa zahtjevima sustava, specifikacijske komponente, projektni
dokumenti na sistemskoj i komponentnoj razini kao i projektni napredak dokumenta.
Osobito za softversku dokumentaciju napisanu prirodnim jezikom, često je teško precizno odrediti
zahtjeve kvalitete i sustavno vrednovati njezinu kvalitetu s obzirom na definirane karakteristike
kvalitete. Zbog toga je uveden novi pristup temeljen na alatu koji olakšava automatsku identifikaciju
nedostataka kvalitete dokumentacije. Ovaj pristup temeljen na alatima oslanja se na skup zahtjeva za
softversku dokumentaciju koji su izričito opisani u standardima i smjernicama za razvoj softvera.
Modeli kvalitete dokumentacije osiguravaju sustavan način za modeliranje zahtjeva kvalitete, za
analizu atributa kvalitete, za procjenu kvalitete i za poboljšanje kvalitete. Korištenje modela kvalitete
omogućuje sustavno grupiranje pravila pomoću atributa kvalitete. Međutim, još nije jasno koji su
atributi kvalitete relevantni za softverske proizvode u praksi.
Najtipičniji problemi s kvalitetom softverske dokumentacije su: nejasna ili nepouzdana softverska
dokumentacija, neadekvaatna, nepotpuna ili nepostojeća softverska dokumentacija, softverska
dokumentacija kojoj nedostaje sljednost, neprimjereno dokumentirane promjene u pogledu softverske
dokumentacije, softver s nedostatkom cjelovitosti i dosljednosti dokumentacije.
Jasno i pravilno definirana programska dokumentacija pomaže u razumijevanju dizajna softverskog
proizvoda, njegove implementacije kao i potrebnih izmjena. Dokumentacija je jedan od najvažnijih
alata za komunikaciju, čak i ako je zastarjela ili nedosljedna.
Komentari izvornog koda (source code comments) nakon kojih slijede modeli podataka i opisi
zahtjeva najvažniji su artefakti dokumentacije za održavanje.
Većina softverskih inženjera ne vidi razloge za pisanje softverske dokumentacije ili nema dovoljno
resursa za praćenje ili poboljšanje kvalitete softverske dokumentacije.
Nekoliko standarda i smjernica za razvoj softvera tvrdi da kvaliteta softverske dokumentacije igra
bitnu ulogu za cijeli softverski proizvod.
Kako ukupna kvaliteta softverskih dokumenata ovisi o različitim atributima kvalitete softverske
dokumentacije, korisno je znati koji su atributi najrelevantniji u praksi.
Nije svaka tehnika analize i osiguranja kvalitete softverske dokumentacije prikladna za jednako dobro
analiziranje svih atributa kvalitete. Stoga treba odrediti tehnike ili metode analize koje ispitanici
koriste u praksi.
Formalnim pregledom podrazumijevamo pregled koji je vođen skupom pravila i proceduralnih
definicija u duhu takozvanih Fagan inspekcija. Međutim, do sada je malo predloženog rada o tome
kako automatski mjeriti kvalitetu softverske dokumentacije. Stoga treba odrediti potražnju i grube
zahtjeve za pristup analize kvalitete softverske dokumentacije temeljene na alatima.
Softverska dokumentacija može se napisati i koristiti za razne aktivnosti razvoja softvera. Većina
softverske dokumentacije je barem djelomično napisana i prilagođena kroz aktivnost Implementacija,
Inženjering zahtjeva i Arhitekture i dizajna.
Pojedinačno rangiranje atributa kvalitete softverske dokumentacije znatno varira. To se može vidjeti u
rasponima atributa kvalitete (objektivnost, stil pisanja, vizualna učinkovitost) koji koriste cijeli
spektar mogućih odgovora. Ipak, važnost atributa kvalitete ne varira tako snažno. Točnost, jasnoća,
dosljednost, čitljivost, strukturiranost i razumljivost se smatraju "vrlo važnima". Ostali atributi
kvalitete (potpunost, konciznost, konkretnost, mogućnost izmjene, objektivnost, stil pisanja,
dostupnost, usmjerenost na zadatak, sljedivost i vizualna učinkovitost) su ocijenjeni "srednje važni".
Prosječna važnost kvalitete softverske dokumentacije smatra "umjereno visokom" za većinu
softverskih proizvoda u praksi.
Standardi koji sadrže uobičajene smjernice za dokumentaciju softvera nisu široko korišteni u praksi.
Nasuprot tome, čini se da su standardi specifikacije zahtjeva važniji.
Koliki je pozitivan utjecaj dobre softverske dokumentacije na atribute kvalitete za vaše softverske
proizvode? Gledajući označene medijane, vidljivo je da je
Atribut kvalitete softverskog proizvoda Analysability visoko je rangiran, tj. smatra se da ovaj atribut
kvalitete softvera pod velikim utjecajem softverske dokumentacije. S druge strane, svi ostali atributi
kvalitete niske razine (Modifikabilnost, Ponovno korištenje, Modularnost i Testabilnost) dobili su
srednji rang. Održivost softverskog proizvoda smatra se atributom kvalitete na koji se najviše utječe u
slučaju loše kvalitete softverske dokumentacije. Loša kvaliteta softverske dokumentacije uglavnom
utječe na analitičnost softverskih proizvoda.
Neformalni pregledi čine najvažniju tehniku analize za sve atribute kvalitete. U prosjeku 47,8 posto
koristi ovu tehniku. Nasuprot tome, čini se da formalni pregledi imaju tek sporednu ulogu (prosjek:
6,9%). Manje od dva posto koristi analize temeljene na alatima, iako se čini da su upotrebljive za
analizu svih vrsta atributa kvalitete; osim za točnost, jasnoću i dostupnost. Većina ne analizira
sažetost, mogućnost izmjene, objektivnost, dostupnost, usmjerenost na zadatak, sljedivost i vizualnu
učinkovitost svoje softverske dokumentacije. Svi ovi atributi kvalitete ocijenjeni su kao "srednje
važni"
Ugrađeni softver jedina je vrsta softvera koja je znatno podzastupljena.
Pretpostavlja se da ne postoji korelacija između količine napisane dokumentacije i iskustva u
poslovima vezanim uz dokumentaciju.
Atributi kvalitete softverske dokumentacije relevantni u praksi.
Točnost se koristi kao sinonim za ispravnost.
Jasnoća je dostupnost nedvosmislenih informacija.
Dosljednost je sposobnost dokumentacije da izbjegne potencijalna ili stvarna odstupanja. Čitljivost je
povezana s temama kao što su formalna ispravnost, glosar i jezični izraz, umnožavanje i praćenje.
Strukturiranost je povezana s formalnom ispravnošću, jer ovaj atribut kvalitete sadrži neka pravila
koja jamče pridržavanje strukture dokumenta i sličnih aspekata.