Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Manuál existoval.
Bol „hotový“.
Bol odovzdaný.
Bol schválený.
A aj tak:
- používatelia volali support
- tester reportoval „bugy“
- onboarding trval dlho
Keď som sa na to pozrela, nebol problém v tom, že by manuál chýbal.
Problém bol v tom, že obsahoval chyby.
Nie gramatické.
Systémové.
Čo sa tu vlastne pokazilo (analýza systému)
Chyby v manuáloch nie sú náhodné.
Opakujú sa.
A vždy majú rovnaký dôsledok:
Používateľ nedokáže vykonať úlohu bez pomoci.
Skutočné náklady (čas, chaos, riziko)
- support rieši základné otázky
- vznikajú falošné bugy
- používateľ robí chyby
- dokumentácia sa obchádza
A hlavne:
Tím prestane manuálu veriť.
Minimálny model riešenia
Najlepšie je ukázať si konkrétne chyby.
- Opis systému namiesto úlohy
Chyba:
Modul fakturácie umožňuje evidenciu faktúr.
Používateľ nevie, čo má spraviť.
Dopad:
- nevie začať
- hľadá pomoc
Správne:
Ako vytvoriť faktúru
- Otvor Fakturáciu
- Klikni na „Nová faktúra“
- Vyplň údaje
- Klikni na „Uložiť“
- Chýbajúci výsledok
Chyba:
Klikni na „Generovať“.
A čo sa stane?
Dopad:
- neistota
- opakovanie krokov
- otázky na support
Správne:
Klikni na „Generovať“.
Výsledok:
Súbor sa stiahne do počítača.
- Preskakujúce kroky
Chyba:
Vyber dátumy a exportuj.
Chýba kontext.
Dopad:
- používateľ sa zasekne
- robí chyby
Správne:
- Otvor Fakturáciu
- Klikni na „Export“
- Vyber rozsah dátumov
- Zvoľ formát
- Potvrď export
- 4. Technický jazyk
Chyba:
Systém vykoná validáciu vstupných dát.
Používateľ tomu nerozumie.
Dopad:
- ignorovanie textu
- chybné kroky
Správne:
Systém skontroluje, či sú údaje správne.
Ak nie, zobrazí chybovú hlášku.
- Screenshot namiesto vysvetlenia
Chyba:
- obrázok bez textu
Dopad:
- používateľ kopíruje obraz
- nevie reagovať na zmenu
Správne:
Klikni na „Export“ (pozri zvýraznenie na obrázku).
Funkcia slúži na stiahnutie dát.
- Zmiešaný Core a Custom
Chyba:
Po vytvorení faktúry môže byť potrebné schválenie.
Pre koho?
Dopad:
- falošné očakávania
- chaos
Správne:
Core:
Faktúra sa zobrazí v zozname.
Custom:
Pre klienta XY musí byť schválená.
- Jeden manuál pre všetkých
Chyba:
Klikni na „Nová faktúra“ a vyplň údaje (pokročilí používatelia môžu použiť kopírovanie existujúcej faktúry).
Text mieša dve úrovne.
Dopad:
- začiatočník nerozumie kontextu
- pokročilý ignoruje zbytočné vysvetlenia
Správne:
Ako vytvoriť faktúru
- Otvor Fakturáciu
- Klikni na „Nová faktúra“
- Vyplň údaje
- Klikni na „Uložiť“
Pre pokročilého:
Faktúru môžeš vytvoriť aj kopírovaním existujúcej.
- Závislosť na UI (krehký manuál)
Chyba:
Klikni na tlačidlo vpravo hore.
UI sa zmení → manuál neplatí.
Dopad:
- neaktuálny manuál
- strata dôvery
Správne:
Klikni na „Export“.
- Manuál bez cieľovej skupiny
Chyba:
V systéme je možné vytvárať rôzne typy dokladov.
Nie je jasné, kto to číta ani čo má spraviť.
Dopad:
- nejasné formulácie
- používateľ nevie, čo sa ho týka
Správne:
Ako vytvoriť faktúru
Tento postup je určený pre používateľa, ktorý vystavuje faktúry zákazníkom.
- Otvor Fakturáciu
- Klikni na „Nová faktúra“
- Vyplň údaje
- Klikni na „Uložiť“
Mini checklist
- Rieši manuál konkrétnu úlohu?
- Sú kroky úplné?
- Je uvedený výsledok?
- Je jazyk zrozumiteľný?
- Je jasné, čo je Core a čo Custom?
- Je text stabilný aj pri zmene UI?
Prepojenie na kvalitu a workflow
Tieto chyby nevznikajú náhodou.
Vznikajú, keď:
- špecifikácia nie je jasná
- testovanie neoveruje scenáre
- dokumentácia sa píše na konci
Manuál je len posledná vrstva.
Ak je chaos v systéme,
bude chaos aj v manuáli.
Krátke zhrnutie
Zlé manuály nevznikajú preto, že by ich ľudia nevedeli písať.
Vznikajú preto, že:
- opisujú systém
- nie úlohu
Dobrý manuál:
- vedie používateľa
- eliminuje otázky
- dá sa použiť bez pomoci
Ak manuál vytvára viac otázok než odpovedí,
je to signál, že niečo v systéme nefunguje.