Systémy softvérovej dokumentácie: Úvod do rôznych systémov generujúcich používateľskú a vývojársku dokumentáciu softvéru. | ||
---|---|---|
Predchádzajúci | Nasledujúci |
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.
Predchádzajúci | Domov | Nasledujúci |
Systémy softvérovej dokumentácie | Systémy používateľskej dokumentácie softvéru |