-- MarianJarembinsky - 03 Nov 2009

Ako správne písať dokumentáciu.

Pre veľké softvérové projekty je normálnou záležitosťou, že dokumentačné záležitosti sa začínajú oveľa skôr ako tie programátorské. Pre niektoré systémy je vypracovaný komplexný dokument požiadaviek na systém. Na jeho správanie, funkcie a iné vlastnosti, ktoré ma spĺňať. Počas fázy vývoja tiež môže pribudnúť celý sortiment dokumentov ako napríklad : plán projektu, špecifikácia dizajnu, plán testovania ...

Je veľmi ťažké definovať aký dokument presne sa bude vyžadovať pre daný systém. To záleží na dohode s klientom, od typu systému, tiež od zaužívaných praktík firmy, ktorá softvér vyvíja. Všeobecne však môžme dokumentáciu zaradiť do dvoch skupín.

Process documentation - Obsahuje proces vývoja a údržby. Plánovanie, rozvrh, organizácia a projektové štandardy.

Product documentation - Popisuje produkt, ktorý je vytváraný. Sýstémová príručka popisuje produkt z pohľadu vývojárov. Používateľská príručka sa zase zameriava na používateľa a oboznámenie ho s projektom.

Process documentation

Obsiahnutých je tu niekoľko kategórií dokumentov

Plány, odhady, rozvrhy - dokumenty vytvorené manažérmi, ktorí určujú a následne kontrolujú vývoj systému.

Správy, oznámenia - dokumenty, ktoré oznamujú aké zdroje boli používané počas procesu vývoja.

Štandardy - dokumenty popisujúce ako má byť vývoj implementovaný. Poznáme štandardy organizácií, národne a medzinárodné štandardy.

Working papers - hlavné dokumenty obsahujúce technickú komunikáciu v projekte. Popisujú záznamy, myšlienky a nápady ľudí pracujúcich na projektoch. Tiež popisujú stratégiu riešenia a vytyčujú problémy, ktoré vznikajú počas práce na projekte.

Poznámky, E-maily - detaily komunikácie medzi vývojármi.

Plány môžu byť zadávané týždenne, mesačne alebo aj denne. Postup sa zvyčajne oznamuje a vyhodnocuje týždenne. Veľa týchto dokumentov stratí svoju podstatu v momente keď sa produkt dostane na svetlo sveta hotový. Niektoré však stále môžu byť použiteľné v prípade, že vzniknú nové požiadavky na softvér.

Product documentation

Slúži na popísanie vyvíjaného produktu. Má dlhšiu životnosť ako Process documentation.

Poznáme 2 typy dokumentov.

Používateľská príručka - Dôležité je pre akého používateľa píšeme dokumentáciu. Hlavne treba rozlišovať úroveň znalostí používateľa. Rozdiel medzi koncovým používateľom a systémovým administrátorom znamená aj rozdiel v dokumentoch pre nich určených. Koncový používateľ sa zaujíma o to ako im softvér môže pomôcť, načo mu bude slúžiť. Systémový administrátor je zodpovedný za udržiavanie softvéru používaného koncovým používateľom. Na základe tejto odlišnosti užívateľov dokážeme používateľskú príručku rozdeliť na 5 typov dokumentov. Tie môžu byť súčasťou jednej príručky ako určité kapitoly.

Funkčný popis systému. Obsahuje opis požiadaviek a heslovite aj funkcie systému. Po prečítaní tohto dokumentu by mal byť používateľ schopný rozhodnúť sa či daný softvér je práve ten čo hľadá.

Manuál k inštalácii. Určená pre systémového administrátora. Mala by obsahovať údaje o inštalácii produktu v rôznych prostrediach, popis súborov a taktiež minimálne hardvérové požiadavky. Používanie automatických inštalačných programov považujú niektorí dodávatelia ako dostatočné, preto tento manuál nepovažujú za potrebný. Avšak faktom stále zostane, že táto príručka môže pomôcť odstrániť rôzne problémy vzniknuté pri inštalácii.

Úvodný manuál. Mal by popisovať "normálne použitie systému" . Ako ho spustiť, ako využiť jeho základne funkcie a možnosti. Táto časť dokumentácie by mala obsahovať aj nejaké názorné ukážky. Tiež upozornenia na časté chyby a ich neskoršie riešenie.

Systémový manuál. Obsahuje podrobný opis funkcií systému. Všetky jeho chybové hlásenia a riešenia k nim. Dôležité je aby tento dokument bol kompletný a obsahoval všetko čo má.

Príručka systémového administrátora. Je určená najmä pre riadiace a kontrolné systémy. Mala by obsahovať správy generované pri kontakte s inými systémami a reakcie na tieto správy.

Systémová príručka. Obsahuje všetky dokumenty, ktoré popisujú systém od špecifikácie požiadaviek až po finálne testovanie. Tak ako používateľská príručka aj systémová má určitú štruktúru. Pre veľké systémy by mala obsahovať:

1) Dokument požiadaviek, spojený s odôvodnením 2) Dokument popisujúci architektúru systému. 3) Dokument obsahujúci architektúru každého programu nachádzajúceho sa v systéme. 4) Pre každý komponent v systéme opis jeho funkcionality 5) Zdrojový kód. Mal by byť riadne okomentovaný. Ak boli použité zmysluplné názvy funkcií, premenných a iných častí kódu tak komentáre nemusia byť až také rozsiahle. 6) Validačný dokument. Popis ako bol každý a jeden program validovaný a popis ako táto validácia korešponduje s požiadavkami. 7) Príručky údržby systému. Popisuje problémy systému. Tiež hardvérové a softvérové závislosti a vývoj systému a jeho dizajnu.

Štruktúra dokumentu

Štruktúra dokumentu ma veľký vplyv na porozumenie a použitie dokumentácie. Preto je potrebné venovať sa štruktúre veľmi opatrne pri vytváraní dokumentu. Dokumentácia by mala byť písaná tak, aby každá kapitola bola tak nezávislá ako to len ide. Aby sa čítanie dokumentácia dalo rozdeliť a aby používateľ nebol nútený pre jednu informáciu prečítať niekoľko kapitol. Indexovanie pomáha k rýchlej orientácii. Preto je jej nevyhnutnou súčasťou.

Dokumentačné štandardy.

Slúžia na uchovanie kvality dokumentácie. Dokumenty písane nejakým určitým štandardom majú presnú štruktúru, vzhľad a kvalitu.

Process Standards. Popisujú prístup pri vytváraní dokumentov. Všeobecne sa má na mysli výber softvéru pre vytvorenie dokumentácie a definovanie kontroly zachovania kvality dokumentu. Ak sa jedná iba o dokumenty, ktoré nevyžadujú vysokú kvalitu nie je potrebné ich kontrolovať. Ak však sa jedná o formálne dokumenty, tie je potrebné kontrolovať navrhnutými metódami kontroly. Vykresľovanie, kontrola, revízia a prekresľovanie sú procesy, ktoré sa stále dookola opakujú až kým nemá dokument potrebnú kvalitu.

Product Standards. Týkajú sa všetkých dokumentov vzniknutých pri vývoji softvéru. Príklady:

Identifikačné štandardy. Veľké projekty produkujú veľa dokumentov, to znamená, že každý dokument musí byť jednoznačne identifikovaný.

Štandardy týkajúce sa štruktúry dokumentu. Definujú štruktúru dokumentu. Tiež by mali špecifikovať pravidlá pre číslovania strán, hlavičiek strán a číslovanie kapitol a podkapitol.

Štandardy týkajúce sa vzhľadu dokumentácie. Obsahujú definície fontov a štýlov použitých v dokumentoch. Použitie znakov firiem, použitie farieb na zvýraznenie dôležitých vecí v dokumente.

Štandardy aktualizácie dokumentácie. Popisujú ako zvýrazniť zmeny v dokumentácii pri jej aktualizácii.

Interchange stadards. Použitie týchto štandardov umožňuje posielať dokumenty elektronicky a následne im vrátiť ich originálnu formu. Sú viac ako len dohoda používať spoločnú verziu systému pre dokumentačný proces. Zahrňujú v sebe určité makrá napríklad na formát textu, na presnú štruktúru stránok. Tieto štandardy tiež môžu limitovať určité fonty písma.

IEEE štandardy. Tieto štandardy zahŕňajú múdrosť a skúsenosti písania dokumentácií a navrhujú štruktúry pre používateľskú príručku. Príklady na zopár tipov pre dobrú dokumentáciu:

Popis ako vytlačiť elektronickú dokumentáciu má byť aj v elektronickej podobe dokumentácie aj vo vytlačenej podobe.

Keďže niektorí používatelia nevedia rozlišovať farby, dokumentácia by mala radšej používať zmeny písma ako použitie farieb (červenej a zelenej) na odlíšenie významu.

Upozornenia a iné dôležité poznámky by mali byť riadne zviditeľnené a odlíšené od zvyšného textu.

Štýly písania

Dobrá dokumentácia potrebuje aj dobré písanie. Napísaná práca musí byť kritizovaná a upravovaná dovtedy kým nie je vytvorený dokument, ktorý splnil požiadavky.

Rady pre písanie :

- používať gramatický správne konštrukcie - nepoužívať dlhé vety, popisujúce viac významov a viac vysvetlení - používať krátke odstavce - precíznosť v definovaní termínov, ktoré chcete použiť - ak je to možné popisy a definície povedať viackrát a rôznym spôsobom - používať kapitoly a podkapitoly - neodkazovať na iné kapitoly len číslom, ale aj názvom alebo popisom kapitoly

Prečo mať presnú a úplnú dokumentáciu k softvéru?

Umožniť kompletné porozumenie programu. Ako príručka pre používateľa. Slúži ako doplnok k systému.