Podstatná otázka dokumentácie

Písanie systémovej dokumentácie je vo výpočtovej technike obľúbená téma. Názory na to, koľko by jej malo byť, sa pohybujú v širokom spektre od nuly (teda vedomosti sa predávajú medzi členmi tímu) po rozsiahle a presné popisy spĺňajúce štandardy. Množstvo je ale len jedným z faktorov. Omnoho zaujímavejší je obsah.

Systémová dokumentácia ako taká predstavuje súbor informácií, ktorý sa používa v čase, kedy je potrebné nájsť odpovede na otázky. Typickým príkladom je, ak sa k vývoju systému dostane človek, ktorý sa na ňom doteraz nepodieľal a potrebuje sa v systéme zorientovať. Inokedy môže slúžiť ako zdroj informácií o špecifickom procese, ktorý v systéme prebieha alebo scénary jeho použitia. Bez ohľadu na to všetko má dokumentácia jednu nevýhodu. Je to popis riešenia. Jeho zdvojene alebo duplicita. Z toho dôvodu je potrebné ju aktualizovať, ak sa riešenie (systém) zmení. Táto aktualizácia je bremenom, ktoré si so sebou dokumentácia nesie a ktoré je nevyhnuté. Čím je dokumentácia väčšia, tým je toto bremeno rozsiahlejšie, čo automaticky vedie k otázke: Čo všetko treba dokumentovať? Aby sa to vyjasnilo, je potrebné si uvedomiť, že vo všetkých spomenutých prípadoch použitia sa v dokumentácii hľadajú odpovede na jednu alebo viac otázok. Poznať tieto otázky a vedieť, ktoré sú natoľko dôležité, že musia byť dokumentované, môže byť pri určovaní rozsahu dokumentácie kľúčové.

Ak hľadáte odpoveď na nejakú otázku, tak veľmi pravdepodobne predstavuje variáciu na niektorú z týchto základných: Čo? Koľko? Kde? Kedy? Ako? Prečo? Dokumentácia v akejkoľvek forme (diagram, text, komentár) vždy slúži na to, aby dala odpoveď na jednu (alebo viac naraz) z nich. Ak si prezriete rôzne typy diagramov, ktoré sa na dokumentovanie používajú a budete skúmať informácie, ktoré obsahujú, zistíte, že vždy dávajú odpoveď na jednu z týchto základných otázok. Napríklad diagram tried odpovedá na otázky Čo? (je z neho vidieť aké triedy daný problém riešia) a Kde? (vidno jednotlivé vzťahy medzi triedami – na diagram sa dá pozerať ako na mapu). Napríklad Use case diagram odpovedá na otázky Čo? (akí používatelia systém používajú), Kedy? (aká je postupnosť operácií – v prípade scenára) a Ako? (ako sa údaje z pohľadu používateľa v systéme spracujú).

Ak sa bavíme o programovacích jazykoch ako je Java, C++, C#, tak zaujímavým faktom je, že na skoro všetky tieto otázky vie odpovedať aj samotné riešenie – teda kód. Nemusí to byť samozrejme tak jednoducho nakreslené, a teda môže to vyžadovať trochu pátrania, ale na väčšinu tých otázok sa odpoveď dá nájsť. Dá sa pozrieť, ako je kód usporiadaný, ako v ňom prebiehajú správy a aké akcie vyvolávajú prvky rozhrania. Kód vie odpovedať skoro na všetky otázky, ale na všetky nie. Najzákernejšou zo všetkých otázok je totiž otázka Prečo?

Prečo? nie je vôbec triviálna otázka. Skrývajú sa za ňou pohnútky k zvoleniu niektorého z množiny riešení. To znamená, že nie je z jednoduchého pohľadu do kódu jasné, prečo sa dané riešenie zvolilo, pretože tá informácia tam jednoducho nie je (rovnako ako tam nie sú obsiahnuté ostatné potenciálne riešenia). Často tieto pohnútky na výber alternatívy môžu prameniť z faktov, ktoré sa v zadaní nenachádzajú (alebo nie priamo). Tiež nie je zrejmé, či v čase výberu riešenia boli jasné všetky alternatívy a pod. Na otázke Prečo? je zákerné aj to, že sa nedá z kódu vygenerovať dokumentácia, ktorá by ju popisovala, čo už je len dôsledok toho, že sa tam tá informácia nenachádza.

Čo je teda najdôležitejšia otázka dokumentácie? Je to otázka: Prečo bolo zvolené dané riešenie? Ak sa vám dostane do rúk kód, ktorý písal iný človek (alebo váš vlastný po roku, dvoch) a ktorý nie je okomentovaný, zo samotného kódu viete postupom času získať odpovede na všetkých prvých 5 otázok (Čo? Koľko? Kde? Kedy? Ako?). Ak to ale všetko pochopíte, tak sa môžete zaraziť na otázke: Prečo bolo zvolené také riešenie aké zvolené bolo? A príde ešte obľúbenejšia otázka vývoja softvéru: To ako je to urobené je naschvál alebo je to chyba? A to je niečo, čo by mohlo a asi aj malo byť obsiahnuté v dokumentácii.

Z toho všetkého vyplýva, že z množiny informácií, ktoré viete do systémovej dokumentácie zapísať, by ste tam určite mali zapísať tie, ktoré odpovedajú na otázku: Prečo? Na všetko ostatné vie odpovedať kód. Podstatné je, aby sa nestratili dôvody, ktoré viedli k danému rozhodnutiu. Ak sa nemýlim, tak v súčastnosti neexistuje diagram, ktorý by dával odpoveď na túto otázku (ak uvažujem bežne používané diagramy, ako sú napríklad diagramy UML). Čo znamená, že často je popis tejto informácie prenechaný na jednoduchý text. Bez ohľadu na to, sú toto asi najcennejšie informácie, ktoré dokáže dokumentácia poskytnúť.