Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Používateľ nahlásil, že sa nedá prihlásiť.
Support to posunul ako bug.
Tester to nevedel reprodukovať.
Vývoj nenašiel chybu.
Nakoniec sa ukázalo, že problém bol v expirovanom tokene.
Stačilo pozrieť log.
Lenže nikto nevedel:
- kde log nájsť
- čo v ňom hľadať
- ako interpretovať chybu
A tak sa riešil incident bez dát.
Čo sa tu vlastne pokazilo (analýza systému)
Systém logoval.
Dokumentácia o logoch neexistovala alebo bola nepoužiteľná.
Typická realita:
- logy existujú, ale nikto nevie kde
- chybové hlášky existujú, ale nikto nevie čo znamenajú
- diagnostika je v hlave seniora
To znamená:
- dokumentácia nepokrýva prevádzku systému
Admin príručka nepopisuje len nastavenie.
Musí pokrývať aj situáciu, keď sa niečo pokazí.
Skutočné náklady (čas, chaos, riziko)
Bez dokumentácie incidentov a logovania:
- support eskaluje aj jednoduché problémy
- tester nevie overiť príčinu
- admin robí pokus-omyl
- vývoj je zahltený otázkami
- incidenty sa riešia dlhšie než treba
Typická veta z praxe:
„Pošli logy.“
Bez toho, aby bolo jasné ktoré.
Minimálny model riešenia
Cieľ nie je popísať všetky logy.
Cieľ je umožniť diagnostiku bez hádania.
1. Kde nájsť logy
Základná informácia, ktorá často chýba:
- umiestnenie logov
- názvy súborov
- prístup (kto ich vidí)
Príklad:
| Typ logu | Umiestnenie | Prístup |
| Aplikačný log | /var/log/app.log | IT admin |
| Audit log | databáza (tabuľka audit_log) | IT admin / biznis admin |
Bez tejto časti je ďalšia dokumentácia nepoužiteľná.
2. Typy logov a ich účel
Nie všetky logy sú rovnaké.
Admin musí vedieť:
- aplikačné logy (chyby systému)
- audit logy (kto čo urobil)
- integračné logy (komunikácia s externými systémami)
Každý typ rieši iný problém.
3. Interpretácia chýb
Najväčší problém v praxi:
Log obsahuje chybu, ale nikto nevie, čo znamená.
Dokumentácia musí obsahovať:
- najčastejšie chybové hlášky
- ich význam
- typickú príčinu
Príklad:
| Chyba | Význam | Príčina |
| AUTH_TOKEN_EXPIRED | Token vypršal | neplatná session |
| DB_CONNECTION_ERROR | Zlyhanie spojenia s DB | nesprávna konfigurácia |
4. Diagnostický postup
Kľúčová časť, ktorá odlišuje dobrú dokumentáciu od zlej.
Namiesto:
„Skontrolujte logy.“
Použi:
- Skontroluj aplikačný log
- Vyhľadaj chybu podľa ID používateľa
- Over čas výskytu
- Porovnaj s audit logom
- Skontroluj konfiguráciu
To je použiteľný postup.
5. Prepojenie na incidenty
Každý incident by mal mať:
- symptóm (čo vidí používateľ)
- príčinu
- riešenie
A tieto informácie sa majú dostať do dokumentácie.
Inak sa ten istý problém rieši opakovane.
6. Kedy eskalovať
Dôležitá časť pre support:
- čo vie vyriešiť sám
- čo patrí adminovi
- čo patrí vývojárovi
Bez toho sa všetko posúva ďalej.
7. Prepojenie na konfiguráciu
Veľa incidentov vzniká kvôli:
- nesprávnej konfigurácii
- chýbajúcim oprávneniam
- nekompatibilite prostredia
Logy pomáhajú tieto veci odhaliť.
Bez dokumentácie sa tieto súvislosti strácajú.
Mini checklist
- Je jasné, kde nájsť logy?
- Sú popísané typy logov?
- Sú vysvetlené najčastejšie chyby?
- Existuje diagnostický postup?
- Sú incidenty zapisované do dokumentácie?
- Je definované, kedy eskalovať?
Ak nie, incidenty sa riešia neefektívne.
Prepojenie na kvalitu a workflow
Logovanie a diagnostika sú základ:
- rýchleho riešenia problémov
- nezávislosti od seniorov
- škálovania supportu
Z testerského pohľadu:
Logy sú zdroj pravdy.
Bez nich tester len odhaduje príčinu.
A to vedie k:
- nesprávnym bug reportom
- zbytočným eskaláciám
- stratám času
Krátke zhrnutie
Logovanie nie je technický detail.
Je to nástroj na pochopenie, čo sa v systéme deje.
Administrátorská príručka musí obsahovať:
- kde sú logy
- čo znamenajú
- ako ich použiť
Bez toho sa incidenty riešia naslepo.
A systém sa stáva závislý na ľuďoch, nie na procesoch.