spájame
slovenskú
IT komunitu
pridaj sa
Registrácia · Login

Peter Špireng 25.4.2012
Hodnoť článok:
0 0

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úť.

Peter Špireng Peter Špireng

"We are all in the gutter, but some of us are looking at the stars." -Oscar Wilde


Hodnoť článok:
0 0

2 komentáre k článku:

Komentovať môžu iba prihlásení

Zaregistruj sa cez bezplatnú registráciu alebo použi login cez Facebook (FB Connect)

Prihlás sa tu, ak už máš profil na Zajtra.sk:


Zabudol som heslo

0 0 tester 30.4.2012 21:02:10
.. problematika dokumentacia zacina pri otazke rozsahu, architektury riesenia a takisto to uzko suvisi ci sa bavime o blackbox rieseni dodavane vendorom, alebo je dodavatel ten isty subjekt, ako ktory tazi z projektu. zial som to v clanku nenasiel a toto su veci, ktorym by som zacal a tvrdo definuju co bude obsahom dokumentacie.
0 0 Matúš Jančík 28.4.2012 11:32:48
Velmi trefne zamyslenie. Odpoved na preco do dokumentacie nedavam a fakt je ten, ze na tuto otazku chcu odpoved vsetci co na projekte spolupracuju. :-)
Zajtra.sk > Život > Veda > Podstatná otázka dokumentácie


Kritika

Vieš ako robiť veci lepšie? Pomôž našim odvážnejším členom a skritizuj im projekty!

Reklama

Seriály zo Zajtra.sk

Reklama