Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Support dostane ticket:
„Export nefunguje.“
Support skúša:
- kliknúť znova
- spýtať sa používateľa
- skúsiť to na inom účte
Nič.
Nakoniec ide za vývojárom:
„Nevieš sa na to pozrieť?“
Vývojár otvorí logy.
Za pár minút vie, kde je problém.
Čo sa tu vlastne pokazilo (analýza systému)
Logy existujú.
Diagnostika existuje.
Ale support o nich nevie, alebo ich nevie použiť.
Typická realita:
- logy sú „niekde na serveri“
- nikto nevie, kde ich nájsť
- nikto nevie, čo v nich hľadať
Dokumentácia buď:
- neexistuje
- alebo obsahuje vetu „skontrolujte logy“
To nie je diagnostika.
Skutočné náklady (čas, chaos, riziko)
Bez logovania a diagnostiky:
- support háda
- eskaluje zbytočne
- zahlcuje vývoj
Vznikajú aj ďalšie problémy:
- dlhý čas riešenia incidentov
- nekonzistentné odpovede
- závislosť na konkrétnych ľuďoch
A hlavne:
support nevie robiť samostatne.
Minimálny model riešenia
Základné pravidlo:
Každá support položka musí obsahovať diagnostiku.
Nie len riešenie.
Čo má obsahovať diagnostika
- kde nájsť logy
- čo konkrétne skontrolovať
- aké hodnoty sú správne
- aké chyby znamenajú problém
Príklad
Symptóm:
Export sa nespustí
Diagnostika:
- skontroluj log exportu (súbor export.log)
- hľadaj chybu „Missing parameter X“
- over hodnotu parametra v konfigurácii
Bez týchto informácií support len skúša.
Logovanie ako súčasť systému
Logovanie nie je detail.
Je to základ:
- diagnostiky
- supportu
- monitoringu
- bezpečnosti
Ak systém neloguje:
- problémy sa nedajú analyzovať
Ak loguje zle:
- logy sú nepoužiteľné
Typické chyby v praxi
- logy existujú, ale nie sú zdokumentované
- logy sú príliš technické bez vysvetlenia
- chýba preklad chýb do „ľudského jazyka“
- nie je jasné, čo je chyba a čo je normálne
Prepojenie na kvalitu a workflow
Logovanie musí byť súčasťou vývoja:
- nová funkcionalita → má logy
- bug → doplniť logovanie, ak chýba
A zároveň súčasť dokumentácie:
- kde logy nájsť
- čo znamenajú
Bez toho:
- support nevie rozhodnúť
- eskalácia je náhodná
Krátke zhrnutie
Logy bez dokumentácie nepomáhajú.
Diagnostika bez logov neexistuje.
Support nepotrebuje vedieť:
- ako systém funguje
Support potrebuje vedieť:
- kde nájsť informácie
- čo znamenajú
- čo s nimi urobiť
Ak dokumentácia neobsahuje diagnostiku,
support je odkázaný na náhodu.