Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Tester hlási bug:
„Systém neposlal notifikáciu.“
Vývojár odpovie:
„To nie je náš systém. To robí externá služba.“
Support povie:
„Ale používateľ to vidí ako jednu aplikáciu.“
A zákazník má jasno:
„Nezaujíma ma, kto za to môže. Nejde to.“
Nakoniec sa zistí, že problém bol v externej službe.
Lenže nikde nebolo jasne napísané:
čo je ešte náš systém a čo už nie.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v chybe.
Problém je v tom, že neexistuje hranica systému.
V dokumentácii chýba základná vec:
Kontext systému.
To znamená:
- čo je súčasť systému
- čo je externá služba
- kto za čo zodpovedá
Bez toho si každý vytvorí vlastnú predstavu:
Používateľ vidí jeden systém.
Support rieši všetko.
Tester nevie, čo testovať.
Vývojár rieši len svoju časť.
A vznikajú konflikty.
Skutočné náklady (čas, chaos, riziko)
Keď nie je jasné, čo je systém:
- bugy sa posielajú medzi tímami
- incidenty sa riešia dlhšie
- support nevie, kam eskalovať
- tester testuje aj veci mimo systému
- zákazník dostáva protichodné odpovede
Najčastejšie:
problém nie je technický
problém je v nejasnej zodpovednosti
Minimálny model riešenia
Stačí jedna vec, ktorú väčšina projektov nemá:
jednoduchý kontextový pohľad na systém.
Základ:
- Definuj hranicu systému
- čo je súčasť produktu
- čo už nie je
- Pomenuj externé závislosti
- platobné brány
- notifikačné služby
- identity provider
- externé API
- Priraď zodpovednosť
- kto spravuje danú časť
- kto rieši incident
- kde končí support
- Popíš tok komunikácie
- čo sa volá kde
- čo sa deje pri chybe
- čo je fallback
Príklad
Používateľ:
„Neprišiel mi e-mail.“
Bez kontextu:
- bug v systéme
- chyba používateľa
- problém v e-mailovej službe
S kontextom:
Systém odošle požiadavku na externú službu MailService.
Za doručenie e-mailu zodpovedá táto služba.
Pri chybe vracia stav 503.
Zrazu je jasné:
čo testovať
čo logovať
kam eskalovať
Mini checklist
Je jasne definované, čo je súčasť systému?
Sú uvedené externé služby?
Je jasné, kto za čo zodpovedá?
Je popísaný tok komunikácie?
Je jasné, čo sa deje pri chybe?
Ak nie, chýba kontext systému.
Prepojenie na kvalitu a workflow
Kontext systému nie je technická formalita.
Bez neho:
- testovanie nemá hranice
- support nevie eskalovať
- dokumentácia si odporuje
- vznikajú falošné bugy
Kontext systému je prvá vec, ktorú potrebuje:
tester
support
vývojár
nový kolega
Ak ju nemáš, všetci sa pýtajú.
Krátke zhrnutie
Kontext systému odpovedá na otázku:
čo je systém a čo nie.
Ak to nie je jasné:
- vzniká chaos
- vznikajú konflikty
- vznikajú zbytočné bugy
Ak to jasné je:
- vieš, čo testovať
- vieš, kam eskalovať
- vieš, kde končí zodpovednosť
A to je základ každej technickej dokumentácie.