Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Manuál bol jeden.
Používali ho:
- nový človek bez skúseností
- skúsený používateľ, ktorý systém pozná roky
Výsledok:
- začiatočník sa stratil po prvom kroku
- pokročilý bol otrávený z „zbytočných vysvetlení“
Obaja mali pravdu.
Manuál nebol zlý.
Bol len pre „nikoho konkrétneho“.
Čo sa tu vlastne pokazilo (analýza systému)
Manuál sa písal ako univerzálny text.
Bez určenia:
- pre koho je
- akú má úroveň znalostí
- čo už používateľ vie
Typické chyby:
- miešanie základov a pokročilých nastavení
- vysvetlenia, ktoré rušia skúseného používateľa
- chýbajúce kroky pre začiatočníka
- jeden scenár pre všetkých
To nie je problém písania.
To je problém cieľovej skupiny.
Skutočné náklady (čas, chaos, riziko)
- začiatočník robí chyby
- pokročilý ignoruje manuál
- support rieši otázky z oboch strán
- onboarding trvá dlhšie
A hlavne:
Manuál sa prestáva používať.
Minimálny model riešenia
Nie všetci používatelia sú rovnakí.
Manuál musí pracovať s úrovňami.
1. Začiatočník vs pokročilý – rozdiel v myslení
Začiatočník:
- nevie, kde začať
- potrebuje presné kroky
- potrebuje kontext („prečo to robím“)
- potrebuje istotu
Pokročilý:
- pozná základ
- hľadá skratky
- nechce čítať zbytočnosti
- rieši konkrétny problém
Ak im dáš rovnaký text,
nebude vyhovovať ani jednému.
2. Nerieš to dvoma manuálmi
Prvá intuícia býva:
„Spravíme manuál pre začiatočníkov a manuál pre pokročilých.“
To zvyčajne nefunguje:
- duplicita obsahu
- rozdiely sa rozídu
- údržba je náročná
Lepšie riešenie:
jedna štruktúra, viac vrstiev.
3. Základná vrstva (pre všetkých)
Každá kapitola musí obsahovať:
- názov úlohy
- základné kroky
- výsledok
To je minimum, ktoré potrebuje každý.
4. Rozšírenie pre začiatočníka
Doplň:
- vysvetlenie pojmov
- kontext („kedy to použiť“)
- upozornenia („na čo si dať pozor“)
5. Rozšírenie pre pokročilého
Doplň:
- skratky
- alternatívne postupy
- tipy na efektivitu
6. Ako to zapísať prakticky
Jedna kapitola môže vyzerať takto:
Ako vytvoriť faktúru
Základný postup:
- Otvor Fakturáciu
- Klikni na „Nová faktúra“
- Vyplň údaje
- Klikni na „Uložiť“
Výsledok:
Faktúra sa uloží do systému.
Pre začiatočníka:
Faktúra je doklad o predaji.
Vytvára sa vždy pred jej odoslaním zákazníkovi.
Pre pokročilého:
Faktúru môžeš vytvoriť aj kopírovaním existujúcej.
Používateľ si vyberie, čo potrebuje.
7. Typická chyba
Snažiť sa „vyvážiť text“.
Výsledok:
- ani jednoduchý
- ani pokročilý
To nefunguje.
Príklad
Neefektívne:
Klikni na „Nová faktúra“.
(Skúsení používatelia môžu použiť aj kopírovanie existujúcej faktúry.)
Text je zmiešaný.
Nikto nie je spokojný.
Funguje:
Oddelené bloky:
- základ
- pokročilé
Mini checklist
- Je jasné, pre koho je základná časť?
- Má začiatočník všetky kroky?
- Vie pokročilý preskočiť vysvetlenia?
- Nie sú informácie zmiešané v jednej vete?
- Dá sa kapitola čítať selektívne?
Prepojenie na kvalitu a workflow
Toto sa nezačína v manuáli.
Začína sa v:
- špecifikácii (čo je základ vs rozšírenie)
- testovaní (basic vs advanced scenáre)
- návrhu UI (jednoduchosť vs flexibilita)
Ak systém nemá jasné vrstvy,
nebude ich mať ani manuál.
Krátke zhrnutie
Používateľský manuál pre „všetkých“ nefunguje.
Dobrý manuál:
- má spoločný základ
- umožňuje rôzne úrovne čítania
- nevnucuje všetko každému
Začiatočník potrebuje istotu.
Pokročilý potrebuje rýchlosť.
Ak to manuál nevie oddeliť,
nebude vyhovovať nikomu.