Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Používateľ napíše na support:
„Nejde mi export faktúry.“
Support otvorí dokumentáciu. Nájde kapitolu:
„Export faktúr umožňuje exportovať dáta do XML formátu…“
Žiadna zmienka o chybe.
Žiadny postup, čo skontrolovať.
Žiadne príklady chýb.
Nasleduje klasika:
- ping na seniora
- hľadanie v Slacku
- improvizácia
A nakoniec sa zistí, že:
- chýba oprávnenie
- alebo je zle nastavený parameter
- alebo export padá na konkrétnom type dát
Dokumentácia existuje.
Ale nepomáha.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v tom, že dokumentácia chýba.
Problém je, že je zlého typu.
Používateľský manuál odpovedá na otázku:
- „Ako to mám použiť?“
Support manuál musí odpovedať na inú otázku:
- „Prečo to nefunguje a čo s tým?“
Typická chyba:
- tím napíše jeden „manuál“ pre všetkých
- zmieša scenáre používania s diagnostikou
- výsledok: nikto v tom nevie rýchlo nájsť odpoveď
Support nepotrebuje opis funkcionality.
Potrebuje diagnostický nástroj.
Toto je zásadný rozdiel, ktorý sa vo firmách často ignoruje.
Skutočné náklady (čas, chaos, riziko)
Keď support nemá správnu dokumentáciu:
- každý incident sa rieši od nuly
- seniori sú neustále vyrušovaní
- onboarding nových ľudí je pomalý
- rovnaké chyby sa riešia opakovane
Vznikajú aj menej viditeľné problémy:
- falošné bugy (support nevie rozlíšiť konfiguráciu vs chybu)
- zlé eskalácie na vývoj
- nekonzistentné odpovede klientom
A hlavne:
firma je závislá na konkrétnych ľuďoch.
Minimálny model riešenia
Základ je prestať písať „manuál“ a začať písať support položky.
Každý problém má mať svoju štruktúru:
Šablóna jednej support položky
- Symptóm
- čo používateľ vidí
- napr. „Export sa nespustí“
- Možné príčiny
- chýbajúce oprávnenie
- zlá konfigurácia
- chyba v dátach
- Diagnostika
- čo konkrétne skontrolovať
- kde to nájsť (logy, nastavenia)
- Riešenie
- konkrétny postup
- nie všeobecná rada
- Eskalácia
- kedy to už nejde riešiť na supporte
- aké údaje poslať vývoju
Toto je úplne iný typ myslenia.
Nie „ako to funguje“, ale:
- „čo sa pokazí“
- „ako to rozpoznať“
- „ako to opraviť“
Prepojenie na kvalitu a workflow
Support manuál nie je samostatný dokument.
Je to výstup z procesu:
- bug reporty
- incidenty
- testovanie
- reálne problémy používateľov
Ak sa incident vyrieši a nezapíše:
- tím sa nič nenaučil
- problém sa zopakuje
Preto by mal byť support manuál súčasťou Definition of Done:
- vyriešený incident → vzniká dokumentačná položka
Toto priamo súvisí s:
- onboardingom
- škálovaním supportu
- prípravou na AI (RAG, chatboty)
Bez štruktúrovanej support dokumentácie AI nemá z čoho odpovedať.
Krátke zhrnutie
- Používateľský manuál vysvetľuje používanie
- Support manuál rieši problémy
Ak sa to zmieša:
- dokumentácia existuje, ale nepomáha
Základná zmena:
- písať cez symptómy, nie cez funkcie
- dokumentovať reálne incidenty
- zaviesť štruktúru „symptóm → príčina → riešenie“
Support manuál nie je text.
Je to nástroj, ktorý znižuje chaos v projekte.