Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Používateľ hlási:
„Platba neprešla.“
V systéme objednávka existuje.
Platba nie.
Support rieši problém.
Tester skúša scenár znova.
Vývojár kontroluje kód.
Nakoniec sa zistí:
problém bol na strane externej platobnej brány.
Lenže v dokumentácii nebolo jasné:
- že ide o externú službu
- kde končí zodpovednosť systému
- čo sa má stať pri chybe
Používateľ vidí jednu aplikáciu.
Systém je v skutočnosti závislý od viacerých.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v integrácii.
Problém je, že integrácie nie sú zdokumentované.
Chýbajú odpovede na základné otázky:
- aké externé systémy používame
- na čo slúžia
- ako s nimi komunikujeme
- čo sa stane, keď nefungujú
Bez toho sa systém javí ako jeden celok.
V realite je to sieť závislostí.
Skutočné náklady (čas, chaos, riziko)
Keď integrácie nie sú jasné:
- bugy sa riešia na nesprávnom mieste
- support nevie eskalovať problém
- tester nevie simulovať chyby
- vývojár nevie rýchlo lokalizovať príčinu
Typická situácia:
problém je mimo systému
ale tím ho rieši vo vnútri
Minimálny model riešenia
Integrácie nemusia byť popísané detailne.
Ale musia byť pochopené.
1. Zoznam externých systémov
- platobná brána
- e-mailová služba
- identity provider
- externé API
Pri každom:
- čo robí
- prečo ho používame
2. Typ komunikácie
- REST API
- message queue
- webhook
- dávkové spracovanie
Toto ovplyvňuje správanie systému.
3. Tok komunikácie
- čo sa volá
- v akom poradí
- čo sa deje pri chybe
Tu sa ukáže realita.
4. Chybové scenáre
- čo sa stane, keď externý systém neodpovie
- čo sa loguje
- čo vidí používateľ
Bez toho vzniká chaos.
5. Zodpovednosť
- čo je náš systém
- čo je externá služba
- kto rieši problém
Toto je kľúčové pre support.
Príklad
Platba:
Bez dokumentácie:
„Platba neprešla.“
S dokumentáciou:
- systém volá platobnú bránu
- čaká na odpoveď
- pri chybe zobrazí hlášku
- transakcia sa neuloží
Zrazu je jasné:
kde hľadať problém
čo testovať
kam eskalovať
Mini checklist
Sú uvedené všetky externé systémy?
Je jasné, na čo slúžia?
Je popísaná komunikácia?
Sú uvedené chybové scenáre?
Je jasné, kto za čo zodpovedá?
Ak nie, integrácie nie sú pochopené.
Prepojenie na kvalitu a workflow
Integrácie sú miesto, kde vzniká najviac problémov.
Bez dokumentácie:
- testovanie nevidí celý flow
- support nevie riešiť incident
- tím rieši problémy naslepo
Integrácie prepájajú systém s okolím.
A práve tam sa ukáže, či systém funguje aj mimo „happy path“.
Krátke zhrnutie
Systém nie je izolovaný.
Závisí od externých služieb.
Ak tieto závislosti nie sú zdokumentované:
- vzniká chaos
- problémy sa riešia nesprávne
Ak zdokumentované sú:
- vieš, kde je problém
- vieš, čo testovať
- vieš, kde končí tvoja zodpovednosť
A to je základ stabilného systému.