Dokumentiranje programov

Dokumentiranje programov je prav tako pomembno, kot je pomembno, da pri nakupu novega izdelka dobimo zraven tudi navodila za uporabo.

Pri dokumentiranju programov moramo pomisliti na to, komu so namenjena:

Uporabniku programa (on potrebuje navodila za uporabo)

Programerju (on potrebuje opis sistema)

Govorimo o tehnični dokumentaciji in o dokumentaciji za uporabnika.

Tehnična dokumentacija

Namenjena je administratorjem sistema in programerjem. Administrator (skrbnik) sistema je tisti, ki mora aplikacijo namestiti na računalnik. V primeru našega osebnega računalnika smo to kar mi. Pri računalniških strežnikih pa je administracija bolj zahtevna.

Danes je veliko aplikacij na področju energije, energije, transporta, omrežij, letalstva, varnosti, varnosti, industrijske avtomatizacije in številnih drugih področij. Tehnična dokumentacija je v takšnih organizacijah pomembna, saj se lahko osnovna in napredna raven informacij v sčasoma spremeni s spremembami arhitekture uporabljene računalniške infrastrukture.

Pod programerjem razumemo tistega, ki bo morda kasneje program vzdrževal in odpravljal napake in pomanjkljivosti. Morda ga bo tudi predeloval, izpopolnjeval in razširjal.

Pomislimo na to, kakšno dokumentacijo programa bi si želeli, če bi bili mi tisti, ki bi morali predelovati program nekoga drugega!!

Ne zanašajmo se, da je program sam po sebi dovolj jasno napisan, da ga bomo po kakšnem letu sami še vedno povsem razumeli (ker bomo razočarani in nam bo žal)!!

Najmanj, kar moramo storiti, je to, da program opremimo z dovolj zgovornim komentarjem. Posebej moramo dokumentirati (ali vsaj opisati s komentarjem) naslednje:

Pomen posameznih spremenljivk
Pomen posameznih funkcij oziroma metod.

Pri funkcijah moramo tudi podati pomen vhodnih parametrov in pomen izhoda, ki ga taka funkcija tvori ali vrača.

Dokumenti o programu so pogosto organizirani v referenčna navodila, kar omogoča programerju hitro iskanje poljubne funkcije ali razreda. Govorimo, da naj ima programer, pa tudi napreden uporabnik na voljo opis takoimenovanega aplikacijskega programskega vmesnika (Application Programming Interface, skrajšano API).

V nekaterih programskih okoljih, kot je na primer Java, imamo tudi možnost avtomatske tvorbe dokumentacije. Pri Javi na primer moramo pred vsako funkcijo pomen te funkcije in njene parametre podati s posebno obliko komentarja, ki ga poseben program nato predela v dokumentacijo.

Pomembno je, da so dokumenti, povezani z izvorno kodo (ki lahko vključuje datoteke README in dokumentacijo API-ja) temeljiti, vendar ne tako podrobni, da postanejo preveč zamudni ali jih je težko vzdrževati. Pogosto se nahajajo različni napotki za dokumentacijo in pregled dokumentacije, ki so specifični za programsko aplikacijo ali programsko opremo, ki jo dokumentirajo API-ji. To dokumentacijo lahko uporabljajo razvijalci, preizkuševalci in končni uporabniki.

Pri bolj obsežnih programih samo komentar ne zadošča. Izdelati moramo tudi »Opis sistema«, v katerem podamo strukturo programa, sestavljenega iz posameznih programskih modulov, pomen posameznih modulov, po možnosti tudi bistvo nekaterih pomembnejših algoritmov.

K dobri dokumentaciji sodi tudi to, da na začetku navedemo avtorstvo in verzijo programa. Temu naj bi sledila še navedba kronoloških sprememb, ki so bile uvedene v program.

Uporabniška dokumentacija

Za razliko od tehnične dokumentacije uporabniški dokumenti preprosto opisujejo, kako se program uporablja.

Uporabniška dokumentacija ponavadi opisuje vsako funkcijo programa in pomaga uporabniku pri uresničevanju teh funkcij. Dober uporabniški dokument lahko tudi nudi temeljito pomoč pri odpravljanju težav. Zelo pomembno je, da nas uporabniški dokumenti ne zmedejo in da so posodobljeni. V takih dokumentih je koristen tudi podroben indeks. Doslednost in preprostost sta tudi zelo dragoceni.

Uporabniško dokumentacijo je mogoče izdelati v različnih spletnih in tiskanih oblikah. Uporabniško dokumentacijo lahko uredite na tri načine.

Vadnica: Tutorski pristop velja za najbolj uporabnega za novega uporabnika, v katerem ga vodi skozi vsak korak uresničevanja določenih nalog.
Tematski pristop: tematski pristop, v katerem se poglavja ali oddelki osredotočajo na posamezna področja je bolj primeren za srednje izkušenega uporabnika.
Seznam ali sklic: Tako je organizirana dokumentacija, v kateri so ukazi ali naloge preprosto navedeni po abecedi ali logično združeni, pogosto prek navzkrižnih indeksov. Slednji pristop je bolj uporaben za napredne uporabnike, ki točno vedo, kakšne informacije iščejo.

Navodila za uporabo so lahko tudi integrirana v sam program v obliki takoimenovane pomoči.