Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Tester hlási:
„Funkcia nefunguje.“
Vývojár odpovie:
„U mňa funguje.“
Support potvrdí:
„U zákazníka to nefunguje.“
Nakoniec sa zistí:
funkcia bola vypnutá konfiguračným parametrom.
Kód bol správny.
Test prešiel.
Len konfigurácia bola iná.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je vo funkcionalite.
Problém je, že konfigurácia nie je zdokumentovaná.
Systém má často:
- konfiguračné parametre
- feature flags
- klientské nastavenia
Lenže nikto presne nevie:
- ktoré existujú
- čo robia
- aké majú hodnoty
- aký majú dopad
Výsledok:
rovnaký systém sa správa inak v rôznych prostrediach.
Skutočné náklady (čas, chaos, riziko)
Keď konfigurácia nie je jasná:
- tester nevie reprodukovať chybu
- support nevie vysvetliť správanie
- vývojár rieši problém, ktorý nie je v kóde
- vznikajú falošné bugy
Typická situácia:
problém nie je v logike
problém je v nastavení
Minimálny model riešenia
Konfiguračné parametre musia byť viditeľné.
1. Zoznam parametrov
Každý parameter má byť zdokumentovaný:
- názov
- typ
- možné hodnoty
- defaultná hodnota
2. Význam parametra
Pri každom parametri má byť jasné:
- čo zapína alebo vypína
- čo mení v správaní systému
Bez toho je parameter nepoužiteľný.
3. Dopad zmeny
Najdôležitejšia časť:
- čo sa stane pri zmene hodnoty
- ktoré funkcionality ovplyvní
- či ide o kritickú zmenu
4. Core vs Custom
- ktoré parametre platia pre všetkých
- ktoré sú klientské
Bez tohto vzniká chaos v produktoch.
5. Prepojenie na prostredia
- ktoré parametre sú aktívne v dev
- ktoré v test
- ktoré v produkcii
To vysvetľuje rozdiely v správaní.
Príklad
Bez dokumentácie:
„Funkcia nefunguje.“
S dokumentáciou:
FEATURE_EXPORT_ENABLED = false
- funkcia exportu je vypnutá
- tlačidlo sa nezobrazuje
- API endpoint vracia chybu
Zrazu je jasné:
že nejde o bug
ale o nastavenie
Mini checklist
Existuje zoznam konfiguračných parametrov?
Je jasné, čo každý parameter robí?
Sú uvedené možné hodnoty?
Je popísaný dopad zmeny?
Je jasné, čo je core a čo custom?
Ak nie, konfigurácia nie je pod kontrolou.
Prepojenie na kvalitu a workflow
Konfigurácia je miesto, kde sa systém „láme“.
Bez dokumentácie:
- testovanie nie je reprodukovateľné
- support nevie riešiť incidenty
- vývojár rieši nesprávny problém
Pre testera je to kľúčové:
Bez znalosti konfigurácie nevieš:
- nastaviť testovacie scenáre
- pochopiť rozdiely medzi prostrediami
- odhaliť falošné bugy
Krátke zhrnutie
Systém nie je len kód.
Je to kombinácia:
kódu
dát
konfigurácie
Ak konfigurácia nie je zdokumentovaná:
- systém je nepredvídateľný
Ak je:
- vieš, čo testovať
- vieš, čo sa zmenilo
- vieš, prečo sa systém správa inak
A to je základ stabilného produktu.