Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Tester hlási:
„Uloženie objednávky trvá 10 sekúnd.“
Vývojár otvorí backend.
Databáza je rýchla.
API odpovedá.
Nakoniec sa zistí, že problém je v komunikácii medzi službami.
Lenže nikto presne nevedel:
koľko komponentov sa do toho zapája
v akom poradí sa volajú
kde sa môže spomaliť systém
Všetko bolo „nejako prepojené“.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v konkrétnej chybe.
Problém je, že systém nemá popísanú architektúru.
Chýba odpoveď na základné otázky:
- z čoho sa systém skladá
- ako spolu komponenty komunikujú
- čo volá čo a v akom poradí
Bez toho si každý predstavuje systém inak.
Vývojár vidí svoj modul.
Tester vidí obrazovku.
Support vidí problém.
Nikto nevidí systém ako celok.
Skutočné náklady (čas, chaos, riziko)
Keď architektúra nie je zdokumentovaná:
- problémy sa hľadajú naslepo
- výkonové chyby sa ťažko diagnostikujú
- integrácie sa rozbíjajú nečakane
- zmeny majú nepredvídateľné dopady
- onboarding trvá dlho
Typická situácia:
problém nie je v jednej časti
problém je v komunikácii medzi nimi
Minimálny model riešenia
Nepotrebuješ zložitý architektonický dokument.
Stačí základný model:
- Zoznam komponentov
- frontend
- backend služby
- databáza
- externé systémy
- Vzťahy medzi nimi
- kto volá koho
- akým spôsobom (API, message queue…)
- Tok komunikácie
- čo sa deje pri bežnej operácii
- v akom poradí sa volania vykonávajú
- Chybové scenáre
- čo sa stane, keď komponent neodpovie
- kde sa chyba prejaví
- čo sa loguje
Príklad
Akcia: vytvorenie objednávky
Bez architektúry:
„Používateľ klikne na Uložiť.“
S architektúrou:
- frontend pošle request na API
- API uloží dáta do databázy
- API zavolá fakturačný systém
- systém pošle správu do notifikačnej služby
Zrazu je jasné:
kde vzniká chyba
kde vzniká oneskorenie
čo testovať
Mini checklist
Sú pomenované všetky hlavné komponenty?
Je jasné, kto s kým komunikuje?
Je popísané poradie volaní?
Sú uvedené externé závislosti?
Je popísané správanie pri chybe?
Ak nie, architektúra nie je zdokumentovaná.
Prepojenie na kvalitu a workflow
Architektúra systému nie je dokument pre architekta.
Je to základ pre:
- testovanie
- debugging
- integrácie
- onboarding
Bez nej:
tester nevidí celý flow
support nevie lokalizovať problém
vývoj robí zmeny naslepo
Architektúra spája všetky pohľady do jedného systému.
Krátke zhrnutie
Architektúra systému odpovedá na otázku:
z čoho sa systém skladá a ako spolu časti komunikujú.
Ak chýba:
- problémy sa hľadajú naslepo
- zmeny majú nepredvídateľné dopady
Ak existuje:
- vieš, kde vzniká chyba
- vieš, čo testovať
- vieš, čo zmena ovplyvní
A to je základ technickej dokumentácie.