Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Support dostane otázku:
„Prečo sa mi nevytvorila faktúra?“
Otvorí dokumentáciu a nájde:
„Modul Fakturácia umožňuje vytvárať, upravovať a exportovať faktúry…“
To je síce pravda.
Ale nepomáha to vyriešiť problém.
Support nevie:
- čo sa pokazilo
- kde to hľadať
- čo má skontrolovať
A ide sa pýtať seniora.
Čo sa tu vlastne pokazilo (analýza systému)
Dokumentácia je napísaná funkčne.
Popisuje:
- čo systém robí
- aké má moduly
- aké má možnosti
Lenže support nehľadá funkcionalitu.
Support hľadá:
- chybu
- príčinu
- riešenie
Typická chyba:
„Modul Export umožňuje…“
Správna otázka supportu:
„Prečo export nefunguje?“
Toto je zásadný rozdiel v myslení, ktorý sa vo firmách často ignoruje.
Skutočné náklady (čas, chaos, riziko)
Keď sa píše funkčne namiesto symptómovo:
- support trávi čas hľadaním namiesto riešenia
- rovnaké problémy sa riešia opakovane
- onboarding nových ľudí je pomalý
- vzniká závislosť na senioroch
A ešte horšie:
- support nevie odlíšiť bug od konfigurácie
- eskaluje zbytočne
- alebo naopak neeskaluje, keď má
Minimálny model riešenia
Základná zmena:
písať cez symptómy, nie cez funkcionality
Funkčný zápis (čo robí väčšina tímov)
- „Export faktúr umožňuje export do XML…“
Použiteľnosť pre support: minimálna
Symptómový zápis (čo support reálne potrebuje)
- „Export sa nespustí“
- „Export skončí chybou 500“
- „Export vytvorí prázdny súbor“
A pod to:
- možné príčiny
- diagnostika
- riešenie
Praktické pravidlá
- píš názvy podľa toho, čo používateľ vidí
- používaj reálne hlášky (nie prepis)
- zapisuj aj „divné správanie“, nielen bugy
- nepremýšľaj ako analytik, ale ako support
Príklad rozdielu
Funkčný zápis:
„Prihlásenie do systému umožňuje autentifikáciu používateľa…“
Symptómový zápis:
„Používateľ sa nevie prihlásiť“
- nesprávne heslo
- účet je zablokovaný
- chýbajúca rola
- výpadok služby
To druhé je použiteľné.
Prepojenie na kvalitu a workflow
Symptómový zápis nevznikne od stola.
Vzniká z reality:
- incidenty
- bug reporty
- testovanie
- otázky používateľov
Každý vyriešený problém je kandidát na dokumentáciu.
Ak sa nezapíše:
- tím sa nič nenaučil
- problém sa zopakuje
Toto je priamy prechod od „riešime chaos“ k „budujeme znalostnú bázu“.
Krátke zhrnutie
Funkčný zápis vysvetľuje systém.
Symptómový zápis rieši problémy.
Support nepotrebuje vedieť:
- čo systém robí
Support potrebuje vedieť:
- prečo to nefunguje
- čo skontrolovať
- čo opraviť
Ak dokumentácia neobsahuje symptómy,
support ju nepoužije.