Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Manuál existoval.
Bol „dobre napísaný“.
A aj tak:
- používatelia volali support
- tester sa pýtal na základné veci
- nový kolega sa nevedel zorientovať
Keď som sa na to pozrela bližšie, problém nebol v tom, že by tam informácie neboli.
Problém bol, že boli napísané tak, že sa nedali použiť.
A vtedy mi to došlo.
Je to rovnaké ako pri obchodníkoch.
Zlý obchodník predáva produkt.
Dobrý obchodník rieši problém zákazníka.
Čo sa tu vlastne pokazilo (analýza systému)
Najčastejšie zlyhanie:
Manuál opisuje systém.
Používateľ potrebuje vykonať úlohu.
To je ten istý rozdiel ako:
- predávať funkcionalitu
- vs riešiť konkrétny problém
Používateľ neprichádza s otázkou:
„Čo tento systém vie?“
Prichádza s otázkou:
- „Ako vytvorím faktúru?“
- „Ako opravím chybu?“
- „Ako dostanem dáta do účtovníctva?“
Ak manuál odpovedá na inú otázku, než si používateľ kladie,
je nepoužiteľný.
Typické chyby z praxe:
- opis modulov namiesto scenárov
- technické formulácie
- chýbajúci výsledok
- preskakujúce kroky
- text bez kontextu („prečo to robím“)
To nie je problém písania.
To je problém myslenia.
Skutočné náklady (čas, chaos, riziko)
- support rieši opakujúce sa otázky
- vznikajú falošné bugy
- onboarding sa spomaľuje
- používateľ robí chyby v procese
A hlavne:
Manuál sa prestáva používať.
Tím si zvykne, že „to aj tak nikto nečíta“.
Minimálny model riešenia
Najlepšie sa to vysvetľuje na konkrétnych príkladoch.
Príklad 1 – opis funkcie vs riešenie problému
Neefektívne:
Modul fakturácie umožňuje evidenciu a správu faktúr.
To je „predaj produktu“.
Používateľ z toho nevie nič spraviť.
Funguje:
Ako vytvoriť faktúru
- Otvor Fakturáciu
- Klikni na „Nová faktúra“
- Vyplň údaje
- Klikni na „Uložiť“
Výsledok:
Faktúra sa uloží do systému.
Príklad 2 – chýbajúci kontext
Neefektívne:
Klikni na „Schváliť“.
Používateľ nevie, prečo to robí.
Funguje:
Klikni na „Schváliť“ (potvrdíš tým faktúru a bude ju možné exportovať).
Používateľ chápe dôsledok.
Príklad 3 – preskakujúce kroky
Neefektívne:
Vyber dátumy a exportuj.
Chýba celý proces.
Funguje:
- Otvor Fakturáciu
- Klikni na „Export“
- Vyber rozsah dátumov
- Zvoľ formát
- Potvrď export
Príklad 4 – technický jazyk
Neefektívne:
Systém vykoná validáciu vstupných dát.
Používateľ tomu nerozumie.
Funguje:
Systém skontroluje, či sú údaje správne.
Ak nie, zobrazí chybovú hlášku.
Príklad 5 – bez výsledku
Neefektívne:
Klikni na „Generovať“.
A čo sa stane?
Funguje:
Klikni na „Generovať“.
Výsledok:
Súbor sa stiahne do počítača.
Mini checklist
- Je každá kapitola úloha, nie opis?
- Rieši konkrétny problém používateľa?
- Sú kroky úplné a v správnom poradí?
- Je jasné, čo sa stane na konci?
- Rozumie textu človek bez znalosti systému?
Prepojenie na kvalitu a workflow
Tieto chyby nevznikajú náhodou.
Vznikajú, keď:
- špecifikácia nie je jasná
- tester nemá scenár, len funkcionalitu
- dokumentácia sa píše na konci
- nikto ju netestuje
Manuál je len posledná vrstva.
Ak tím „predáva funkcionalitu“ už v špecifikácii,
bude ju „predávať“ aj v manuáli.
Ak tím rieši problém používateľa,
bude to vidieť aj v dokumentácii.
Krátke zhrnutie
Rozdiel medzi dobrým a zlým manuálom nie je v dĺžke ani v štýle.
Je v tom, či:
- rieši problém používateľa
- vedie ho k výsledku
- eliminuje otázky
Zlý manuál opisuje systém.
Dobrý manuál rieši situáciu.
Ak sa podľa manuálu nedá pracovať bez vysvetlenia,
je to rovnaké, ako keď obchodník síce rozpráva…
ale nepomáha.