Takmer každý vývojár softvéru už bol niekedy v živote postavený pred
problematiku dokumentácie k jeho projektu. Táto na prvý pohľad banálna
záležitosť však v sebe skrýva viac problémov, ako by sa na prvý pohľad zdalo.
Softvér, ktorý neobsahuje kvalitnú obsažnú a vyčerpávajúcu dokumentáciu je už
dopredu odsúdený na zánik. V našom dokumente sa vám pokúsime načrtnúť niektoré z
možných spôsobov rýchleho a efektívneho zdokumentovania softvérového produktu.
Základným faktorom, ktorý je treba mať na zreteli, je cielová skupina. Odlišný
typ informácií je zaujímavý pre bežného používateľa softvéru, iný pre
vývojára aplikácie. Tomu treba následne prispôsobiť formu aj obsah
dokumentácie. Preto odlišujeme dva rôzne typy dokumentácie:
Používateľská dokumentácia
Bežneho používateľa spravidla nezaujíma štruktúra softvéru ani jeho vnútorná
implementácia. Nie je preňho dôležité ako sú veci urobené, aké prostiedky a
programovacie jazyky boli pri vývoji použité, ale ako v skutočnosti program
funguje, ako sa používa a taktiež v akom prostredí a pod akým operačným systémom
je spustiteľný. Preto by sa mal dôraz klásť na podrobné, ale hlavne zrozumiteľné
vysvetlenie všetkých funkcií a možností programu.
Je lepšie, keď je používateľská dokumentácia písaná niekým iným ako samotným
autorom programu. Ten totiž považuje mnoho vecí za úplne jasné a samozrejmé,
ktoré však už pre bežného používateľa také jasné a samozrejmé nie sú. Vhodné je,
keď používateľská dokumentácia obsahuje množstvo príkladov a keď je celkovo
písaná s vedomím, že ju nebude čítať osoba rozumejúca programovaniu.
Vývojárska dokumentácia
Príslušný vývojár pracujúci na projekte potrebuje mať zdokumentované všetky
vnútorné technické záležitosti softvéru, ako sú napr. hierarchia dedičnosti
tried, popis datových štruktúr a ich atribútov, zoznam zdrojových súborov,
zoznam globálnych identifikátorov a pod. Medzi informácie takéhoto charakteru
patrí tiež opis správneho použitia príslušných vývojových nástrojov, slúžiacich
k zostavovaniu programu.
Základným účelom existencie vývojárskej dokumentácie je údržba a rozšíriteľnosť
softvérového produktu. Nutné je zdokumentovať najmä všetky neštandartné
programovacie konštrukcie a taktiež podrobný popis postupu ladenia programu.
Z prechádzajúcich definícií je teda zrejmé, že tieto dva typy dokumentácie sú
úplne odlišné. Nie je možné, aby dokumentácia prvého typu nahrádzala druhú alebo
opačne. U vývojárskej dokumentácie platí pravidlo písať ju priamo za behu
vytvárania programu. Ak sa vnútorná implementácia alebo štruktúra zmení, zmení
sa aj príslušná časť dokumentácie. Používateľskú dokumentáciu je vhodné taktiež
začať písať čo najskôr, ale až po dosiahnutí aspoň základnej funkcionality
programu.
Oba typy dokumetácie píšu iní ľudia a tomu sú aj prispôsobené nástroje na ich
tvorbu a údržbu. Ich použitie bude opísané v nasledujúcich kapitolách tohto
dokumentu.
| 
Login
Registration
Slovak
