Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Support dokumentácia existuje.
Každý ju píše po svojom:
- niekto opisuje funkcionalitu
- niekto píše voľný text
- niekto dá len pár bodov
Výsledok:
- nedá sa v tom vyhľadávať
- nedá sa to použiť konzistentne
- každá odpoveď vyzerá inak
A hlavne:
rovnaké problémy sa riešia rôznymi spôsobmi.
Čo sa tu vlastne pokazilo (analýza systému)
Chýba jednotný model zápisu.
Bez šablóny:
- každý zapisuje podľa seba
- informácie sú neúplné
- chýbajú kľúčové časti (diagnostika, eskalácia)
Dokumentácia existuje, ale nie je použiteľná.
Skutočné náklady (čas, chaos, riziko)
Bez jednotnej štruktúry:
- support hľadá dlhšie
- riešenia sú nekonzistentné
- onboarding je pomalý
Vznikajú aj ďalšie problémy:
- chýbajú kritické informácie
- workaroundy sa miešajú s riešeniami
- eskalácie sú nejasné
A hlavne:
nedá sa to škálovať.
Minimálny model riešenia
Základ:
Každá support položka má rovnakú štruktúru.
Nie odporúčanie.
Pravidlo.
Univerzálna šablóna
1. Názov (symptóm)
- krátky
- konkrétny
- podľa jazyka používateľa
Príklad:
„Používateľ sa nevie prihlásiť“
2. Popis symptómu
- čo používateľ vidí
- prípadne chybová hláška
3. Možné príčiny
- zoznam najčastejších dôvodov
- nie jedna „pravda“
4. Diagnostika
- čo konkrétne skontrolovať
- kde to nájsť
- aké hodnoty sú správne
5. Riešenie
- presný postup
- vykonateľný krok za krokom
6. Workaround (ak existuje)
- jasne označený ako dočasný
- s obmedzeniami
- prepojený na bug
7. Eskalácia
- kedy to už nejde riešiť na supporte
- čo musí obsahovať eskalácia
8. Platnosť (Core vs Custom)
- pre koho riešenie platí
- napr. všetci klienti / klient XY
9. Tagy
- modul
- typ problému
- klient
10. Prepojenia
- bug report
- súvisiace problémy
- ďalšie články
Príklad kompletnej položky
Názov:
Používateľ sa nevie prihlásiť
Popis:
Po zadaní údajov sa zobrazí chyba „Invalid credentials“
Možné príčiny:
- nesprávne heslo
- účet je zablokovaný
- chýbajúca rola
Diagnostika:
- over login
- skontroluj stav účtu
- pozri log autentifikácie
Riešenie:
- reset hesla
- odblokovanie účtu
- priradenie roly
Eskalácia:
- chyba 500 v logu
- neznáma chyba
Prepojenie na kvalitu a workflow
Šablóna nie je len dokumentačný nástroj.
Je to:
- kontrolný mechanizmus kvality
- základ pre konzistentnú komunikáciu
- základ pre škálovanie supportu
A zároveň:
je to vstup pre AI a automatizáciu.
Krátke zhrnutie
Bez šablóny:
- každý píše inak
- dokumentácia sa nedá použiť
So šablónou:
- všetko má rovnakú štruktúru
- support vie, kde čo nájsť
- tím funguje konzistentne
Šablóna nie je formalita.
Je to spôsob, ako z chaosu spraviť systém.