Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Support dostane ticket:
„Používateľ sa nevie prihlásiť.“
Začne sa klasické kolečko:
- „Aký má login?“
- „Aká je chyba?“
- „Funguje to iným?“
- „Čo sa menilo?“
Každý rieši rovnaké otázky stále dokola.
A dokumentácia?
Buď neexistuje, alebo obsahuje kapitolu:
„Prihlásenie do systému umožňuje…“
To supportu nepomôže.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je, že neexistuje dokumentácia.
Problém je, že nemá štruktúru použiteľnú pre support.
Najčastejšie chyby:
- opis funkcie namiesto riešenia problému
- dlhé odseky bez jasného postupu
- chýbajú konkrétne scenáre
- chýba diagnostika
Support potrebuje rýchlo:
- identifikovať problém
- overiť príčinu
- nájsť riešenie
Ak to dokumentácia neumožňuje, je prakticky nepoužiteľná.
Skutočné náklady (čas, chaos, riziko)
Bez jednotnej štruktúry vzniká:
- každé riešenie od nuly
- závislosť na senioroch
- pomalé reakcie na klienta
- nekonzistentné odpovede
A najhoršie:
rovnaký problém sa rieši opakovane, ale nikdy sa nezapíše.
To znamená, že firma nebuduje znalostnú bázu.
Minimálny model riešenia
Základ je jednoduchý:
Každá support položka má rovnakú štruktúru.
1. Symptóm (čo používateľ vidí)
Popis problému očami používateľa.
- konkrétny
- krátky
- vyhľadateľný
Príklady:
- „Používateľ sa nevie prihlásiť“
- „Export sa nespustí“
- „Faktúra sa neuloží“
Nie:
- „Problém s autentifikáciou“
- „Chyba modulu fakturácie“
2. Možné príčiny
Prehľad najčastejších dôvodov.
- chýbajúce oprávnenie
- nesprávna konfigurácia
- neplatné dáta
- výpadok služby
Dôležité:
- nepísať jednu „pravdu“
- uviesť reálne varianty z praxe
3. Diagnostika (čo overiť)
Kľúčová časť, ktorú firmy často vynechávajú.
Konkrétne kroky:
- kde kliknúť
- čo skontrolovať
- kde nájsť logy
- akú hodnotu očakávať
Príklad:
- skontroluj rolu používateľa
- over nastavenie parametra X
- pozri log v súbore Y
- skontroluj odpoveď API
Bez diagnostiky support len háda.
4. Riešenie
Presný postup, čo urobiť.
- zmeniť nastavenie
- doplniť oprávnenie
- opraviť dáta
- reštartovať službu
Nie:
- „skontrolujte nastavenia“
- „kontaktujte administrátora“
Riešenie musí byť vykonateľné.
5. Eskalácia (kedy to už nie je support)
Jasná hranica:
- kedy to ide na L2 / L3
- kedy je to bug
- kedy je to infra problém
A hlavne:
- čo má support priložiť
Príklad:
- ID používateľa
- čas chyby
- logy
- request/response
Bez toho vývoj nemá z čoho pracovať.
Príklad kompletnej support položky
Symptóm:
Používateľ sa nevie prihlásiť
Možné príčiny:
- nesprávne heslo
- účet je zablokovaný
- chýbajúca rola
- výpadok autentifikačnej služby
Diagnostika:
- over login a heslo
- skontroluj stav účtu v admin rozhraní
- over priradené roly
- skontroluj log autentifikácie
Riešenie:
- reset hesla
- odblokovanie účtu
- priradenie správnej roly
Eskalácia:
- ak log obsahuje chybu 500 → poslať vývoju
- priložiť: user ID, timestamp, log
Prepojenie na kvalitu a workflow
Táto štruktúra nevzniká sama.
Musí byť súčasťou procesu:
- incident → vznik support položky
- bug report → doplnenie dokumentácie
- release → aktualizácia riešení
A ideálne:
Definition of Done obsahuje:
- „existuje support dokumentácia pre novú funkcionalitu“
Toto je priamy nástroj na:
- zníženie chaosu
- rýchlejší onboarding
- prípravu na AI
Krátke zhrnutie
Support dokumentácia nie je text.
Je to databáza riešení problémov.
Ak nemá jednotnú štruktúru:
- nedá sa vyhľadávať
- nedá sa škálovať
- nedá sa použiť pre AI
Základ:
- Symptóm
- Príčina
- Diagnostika
- Riešenie
- Eskalácia
Ak sa podľa dokumentácie nedá vyriešiť problém bez telefonátu seniorovi,
dokumentácia zlyháva.