Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Manuál existoval. Mal 60 strán.
Používateľ zavolal support a pýtal sa:
„Kde nájdem export?“
Odpoveď bola na strane 42.
Lenže:
- názov kapitoly bol „Dátové operácie“
- text bol písaný technicky
- nebol tam konkrétny scenár
- screenshot bol zo starej verzie
Používateľ ten manuál nečítal.
A nie preto, že nechcel.
Preto, že sa v ňom nedalo orientovať.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je „ľudia nečítajú manuály“.
Problém je:
manuál je písaný z pohľadu systému, nie používateľa.
Typické chyby:
- kapitoly podľa modulov, nie podľa úloh
- technický jazyk („validácia dát“, „entita“)
- chýba kontext („kedy to mám použiť?“)
- chýba očakávaný výsledok
- neexistuje prepojenie na reálne scenáre
Toto je dôsledok jedného rozhodnutia:
Manuál sa píše podľa toho, ako je systém navrhnutý.
Nie podľa toho, ako ho človek používa.
Skutočné náklady (čas, chaos, riziko)
Toto sa v praxi neprejaví ako „zlá dokumentácia“.
Prejaví sa to takto:
- support odpovedá na základné otázky
- tester reportuje „bug“, ktorý je len nepochopenie
- používateľ robí chyby v procese
- onboarding nového človeka trvá násobne dlhšie
A hlavne:
Manuál prestáva byť zdrojom pravdy.
Stáva sa len „papierom, ktorý existuje“.
Minimálny model riešenia
Používateľský manuál musí byť postavený na úlohách, nie na systéme.
Základná štruktúra jednej kapitoly:
- Kedy túto funkciu použiť
- Kroky (číslované, bez preskakovania)
- Príklad (reálny scenár)
- Očakávaný výsledok
- Poznámky / obmedzenia
Príklad
Zlé:
Modul exportu umožňuje generovanie XML súborov na základe definovaných parametrov.
Správne:
Ako exportovať faktúry do XML pre účtovníctvo
- Otvor modul Fakturácia
- Klikni na „Export“
- Vyber rozsah dátumov
- Zvoľ formát XML
- Klikni na „Generovať“
Výsledok:
Súbor XML sa stiahne do počítača a je pripravený na import do účtovného systému.
Obmedzenie:
Export obsahuje len schválené faktúry.
Mini checklist pre manuál
- Dá sa podľa toho spraviť úloha bez otázok?
- Je jasné „prečo to robím“?
- Sú kroky kompletné (žiadne preskoky)?
- Je výsledok explicitne napísaný?
- Sú pomenovania rovnaké ako v aplikácii?
Prepojenie na kvalitu a workflow
Používateľský manuál nevzniká izolovane.
Je výsledkom reťazca:
Špecifikácia → Implementácia → Test → Manuál
Ak tester:
- vidí nejasný krok
- nevie dokončiť scenár
- musí sa pýtať vývojára
tak ten problém nie je len v teste.
Ten problém sa prenesie do manuálu.
A následne k používateľovi.
Preto manuál nie je „dokument navyše“.
Je to posledná kontrola, či systém dáva zmysel.
Krátke zhrnutie
Používateľ nečíta manuál preto, že je lenivý.
Nečíta ho, pretože:
- nie je písaný jeho jazykom
- nerieši jeho situáciu
- nedá sa podľa neho pracovať
Dobrý manuál:
- vedie používateľa krok za krokom
- odpovedá na konkrétnu potrebu
- eliminuje otázky, nie ich vytvára
Ak sa podľa manuálu nedá pracovať bez telefonátu na support,
manuál zlyhal.
A tým pádom zlyhal aj proces, ktorý ho vytvoril.
Ak sa pozrieš kriticky, toto je miesto, kde sa láme realita projektu. Nie v kóde. V tom, či sa systém dá používať bez vysvetľovania.