Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
V projekte „architektúra existovala“.
Bol tam obrázok.
Krásny diagram.
Krabice, šípky, názvy služieb.
Keď prišiel problém, všetci ho otvorili.
A potom nasledovala otázka:
„A čo to vlastne znamená?“
Diagram ukazoval prepojenia.
Ale neukazoval správanie.
Nakoniec aj tak rozhodol senior.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je, že architektúra nie je zdokumentovaná.
Problém je, že je zapísaná nepoužiteľne.
Najčastejšie chyby:
Len diagram
- vidíš komponenty
- nevieš, čo robia
Len text
- veľa detailov
- chýba prehľad
„Máme to v hlave“
- nikto nový sa nechytá
Architektúra nie je obrázok.
Ani dokument.
Je to spôsob, ako pochopiť systém.
Ak sa podľa nej nedá pracovať, zlyhala.
Skutočné náklady (čas, chaos, riziko)
Keď architektúra nie je použiteľná:
- problémy sa riešia cez ľudí, nie cez dokumentáciu
- onboarding trvá dlho
- testovanie nevidí celý flow
- zmeny majú nepredvídateľné dopady
Typická situácia:
diagram existuje
ale rozhodnutia sa robia mimo neho
Minimálny model riešenia
Nepotrebuješ dokonalú architektúru.
Stačí použiteľná.
Základný model má tri časti:
- Diagram (prehľad)
- komponenty systému
- ich prepojenia
Bez detailov.
Cieľ: rýchlo pochopiť systém.
- Text (význam)
Ku každému komponentu:
- čo robí
- čo prijíma
- čo vracia
- od čoho závisí
- čo sa stane pri chybe
Toto je to, čo v diagramoch chýba.
- Flow (scenár)
Konkrétna operácia:
- čo sa volá
- v akom poradí
- čo sa deje pri chybe
Príklad:
- frontend pošle request
- API uloží dáta
- zavolá externý systém
- spracuje odpoveď
Tu sa architektúra mení na realitu.
Príklad
Bez použiteľnej architektúry:
„Uloženie objednávky je pomalé.“
S použitelnou architektúrou:
- frontend → API
- API → databáza
- API → externý systém
- odpoveď späť
Zrazu vieš:
kde hľadať problém
čo testovať
čo môže zlyhať
Mini checklist
Existuje diagram systému?
Je jasné, čo robí každý komponent?
Je popísaná komunikácia medzi nimi?
Existuje aspoň jeden reálny flow?
Je popísané správanie pri chybe?
Ak nie, architektúra nie je použiteľná.
Prepojenie na kvalitu a workflow
Použiteľná architektúra nie je dokument pre architekta.
Je to nástroj pre:
- testovanie
- debugging
- integrácie
- onboarding
Bez nej:
tester nevidí celý systém
support nevie lokalizovať problém
vývoj robí zmeny naslepo
Architektúra je spoločný jazyk tímu.
Krátke zhrnutie
Architektúra systému sa nedá zapísať jedným spôsobom.
Potrebuješ:
- diagram (prehľad)
- text (význam)
- flow (realita)
Ak máš len jedno z toho:
dokumentácia zlyhá
Ak máš všetky tri:
dá sa podľa nej pracovať.