Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Funkcionalita prestala fungovať.
Používateľ ju nevidel.
Support to označil ako bug.
Tester to nevedel reprodukovať.
Nakoniec sa ukázalo, že bola vypnutá konfigurácia.
V dokumentácii bola uvedená.
Len ako názov parametra.
Bez vysvetlenia:
- čo robí
- kedy sa používa
- čo sa stane, keď ju zmením
Výsledok:
Tri tímy riešili „bug“, ktorý bol nastavenie.
Čo sa tu vlastne pokazilo (analýza systému)
Konfigurácia bola zdokumentovaná ako zoznam.
Nie ako správanie systému.
Typický zápis v dokumentácii:
FEATURE_ENABLED = true/false
To nestačí.
Chýba kontext:
- aký je význam parametra
- aké má väzby na iné nastavenia
- aký je dopad zmeny
Bez toho dokumentácia neplní svoju úlohu.
Konfigurácia nie je technický detail.
Je to riadenie správania systému.
Skutočné náklady (čas, chaos, riziko)
Ak konfigurácia nie je správne zdokumentovaná:
- vznikajú falošné bugy
- tester testuje nesprávne scenáre
- support dáva nesprávne odporúčania
- admin robí pokus-omyl
- systém sa správa nekonzistentne medzi klientmi
A typická veta z praxe:
„To musí byť zapnuté, inak to nefunguje.“
Bez vysvetlenia prečo.
Minimálny model riešenia
Cieľ nie je mať zoznam parametrov.
Cieľ je popísať dopady konfigurácie.
1. Každý parameter musí mať význam
Namiesto:
EXPORT_ENABLED = true/false
Použi:
- Názov: EXPORT_ENABLED
- Popis: Zapína alebo vypína export dát
- Default hodnota: false
- Kto nastavuje: IT admin
- Rozsah hodnôt: true / false
2. Dopad zmeny (kľúčová časť)
Každý parameter musí obsahovať:
- čo sa stane pri zapnutí
- čo sa stane pri vypnutí
Príklad:
- true: tlačidlo Export je dostupné
- false: export nie je dostupný, tlačidlo sa nezobrazí
Bez tejto časti je dokumentácia neúplná.
3. Závislosti medzi parametrami
Veľmi častý problém:
Parametre nefungujú izolovane.
Príklad:
- EXPORT_ENABLED = true
- USER_ROLE = admin
Dopad:
Export je dostupný len pre admina.
Dokumentácia musí obsahovať:
- väzby medzi parametrami
- podmienky, za ktorých funkcionalita funguje
4. Hraničné prípady a chyby
Dôležité je uviesť:
- čo sa stane pri nesprávnej hodnote
- aké chyby vzniknú
- ako sa prejavia
Príklad:
„Ak je nastavená neplatná hodnota, export zlyhá a zapíše chybu do logu.“
5. Core vs Custom konfigurácia
Nie všetky parametre platia pre všetkých.
Dokumentácia musí jasne uvádzať:
- ktoré nastavenia sú súčasť produktu
- ktoré sú klientské úpravy
Inak vznikajú nesprávne očakávania.
6. Prepojenie na roly
Každý parameter musí mať:
- kto ho nastavuje
- kto ho môže meniť
- kto nesie zodpovednosť
Bez toho vznikajú konflikty.
Mini checklist
- Má každý parameter popis a význam?
- Sú uvedené dopady zmien?
- Sú definované závislosti?
- Sú uvedené hraničné prípady?
- Je jasné, kto parameter nastavuje?
Ak nie, konfigurácia nie je dokumentovaná, len zapísaná.
Prepojenie na kvalitu a workflow
Konfigurácia je miesto, kde sa stretáva:
- vývoj
- testovanie
- prevádzka
- support
Ak nie je zdokumentovaná:
- tester nevie, čo testuje
- support nevie, čo rieši
- admin nevie, čo mení
Z testerského pohľadu:
Veľa chýb nie sú bugy.
Sú to nesprávne konfigurácie.
Krátke zhrnutie
Dokumentovať konfiguráciu neznamená vypísať parametre.
Znamená:
- vysvetliť ich význam
- popísať dopady
- ukázať závislosti
- definovať zodpovednosť
Bez toho je systém nepredvídateľný.
A dokumentácia len vytvára falošný pocit istoty.