Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Tester hlási bug:
„Export nefunguje.“
Vývojár odpovie:
„U nás funguje.“
Support doplní:
„U iných zákazníkov to ide.“
Nakoniec sa zistí:
funkcionalita je upravená len pre konkrétneho klienta.
V dokumentácii je popísaný „štandardný systém“.
Reálne správanie je iné.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v chybe.
Problém je, že dokumentácia nerozlišuje:
- čo je Core (spoločné pre všetkých)
- čo je Custom (upravené pre klienta)
V mnohých projektoch:
- systém sa vyvíja ako produkt
- ale zároveň sa upravuje pre klientov
Dokumentácia však ostáva jednotná.
Výsledok:
- tester testuje nesprávne správanie
- support komunikuje nesprávne informácie
- vývoj vysvetľuje výnimky ústne
Skutočné náklady (čas, chaos, riziko)
Keď Core a Custom nie sú oddelené:
- vznikajú falošné bugy
- testovanie je nekonzistentné
- onboarding je zmätočný
- support nevie, čo platí pre konkrétneho klienta
Typická situácia:
správanie je správne
ale len pre iného klienta
Minimálny model riešenia
Treba oddeliť vrstvy.
- Core dokumentácia
Obsahuje:
- základné fungovanie systému
- architektúru
- API
- dátový model
- pravidlá, ktoré platia pre všetkých
Toto je „zdroj pravdy“.
- Custom dokumentácia
Obsahuje:
- klientské úpravy
- výnimky
- špecifické konfigurácie
- odchýlky od Core
Musí byť jasne označená.
- Prepojenie Core ↔ Custom
- na ktorú časť Core sa Custom viaže
- čo presne mení
- aký má dopad
Bez tohto sa vrstvy rozpadnú.
- Identifikácia klienta / prostredia
Musí byť jasné:
- pre koho dokumentácia platí
- v ktorom prostredí
- v ktorej verzii
Príklad
Bez rozlíšenia:
„Export funguje takto…“
S rozlíšením:
Core:
- export generuje súbor CSV
Custom (klient A):
- export generuje XML
- obsahuje extra polia
Zrazu je jasné:
čo testovať
čo je správne správanie
čo je výnimka
Mini checklist
Je jasné, čo je Core a čo Custom?
Je Core dokumentácia oddelená?
Sú klientské úpravy označené?
Je popísaný dopad Custom zmien?
Je jasné, pre koho dokumentácia platí?
Ak nie, dokumentácia neodráža realitu systému.
Prepojenie na kvalitu a workflow
Core vs Custom je kľúčové pre:
- testovanie
- support
- onboarding
- release
Bez toho:
- tester testuje nesprávne scenáre
- support dáva nesprávne odpovede
- vývoj rieši nedorozumenia
Pre testera:
najdôležitejšia otázka je:
Testujem Core alebo Custom?
Krátke zhrnutie
Systém nie je vždy jeden.
Má:
- spoločné jadro (Core)
- klientské úpravy (Custom)
Ak to nie je zdokumentované:
- vzniká chaos
- tím si nerozumie
Ak je:
- vieš, čo platí
- vieš, čo testovať
- vieš, čo je výnimka
A to je základ škálovateľného produktu.