Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Vyšla nová verzia systému.
Funkcionalita sa nezmenila zásadne.
Len:
- pribudlo tlačidlo
- zmenil sa názov jedného poľa
- presunul sa krok do inej časti obrazovky
Manuál bol zrazu nepoužiteľný.
Používateľ postupoval podľa neho a zasekol sa na kroku:
„Kliknite na tlačidlo Export vpravo hore.“
Lenže tlačidlo už nebolo vpravo hore.
Support zahltený.
Tester reportuje „bug“.
Vývojár odpovedá: „Je to správne, len je to inde.“
Manuál zostal v starej verzii reality.
Čo sa tu vlastne pokazilo (analýza systému)
Manuál bol napísaný tak, že bol viazaný na konkrétnu verziu UI.
Typické chyby:
- presná poloha prvkov („vpravo hore“, „tretie tlačidlo“)
- screenshoty bez kontextu
- názvy tlačidiel bez významu
- chýba vysvetlenie, čo krok robí
- žiadne oddelenie Core vs drobné UI zmeny
Takýto manuál je krehký.
Stačí malá zmena a rozpadne sa.
Skutočné náklady (čas, chaos, riziko)
- každá verzia = prepis manuálu
- support rieši „nefunkčné návody“
- onboarding nových ľudí sa spomaľuje
- vznikajú falošné bugy („podľa manuálu to nefunguje“)
A hlavne:
Dokumentácia prestáva byť dôveryhodná.
Používateľ si zvykne:
„Radšej sa opýtam, než by som to čítal.“
Minimálny model riešenia
Cieľ nie je mať „presný manuál pre túto verziu“.
Cieľ je mať manuál, ktorý prežije zmeny.
1. Píš cez význam, nie cez pozíciu
Zlé:
Klikni na tlačidlo Export vpravo hore.
Lepšie:
Klikni na tlačidlo Export (slúži na stiahnutie dát do súboru).
Používateľ hľadá význam, nie polohu.
2. Minimalizuj závislosť na screenoch
Screenshot nie je pravda.
Je to momentka jednej verzie.
Používaj ho len ako doplnok, nie ako nosnú informáciu.
3. Vysvetli, čo krok robí
Ak sa UI zmení, význam zostáva.
Príklad:
Vyber rozsah dátumov (určuje, ktoré faktúry budú zahrnuté do exportu).
Aj keď sa pole presunie, používateľ vie, čo hľadá.
4. Oddeľ stabilné od nestabilného
Nie všetko v systéme sa mení rovnako.
- Core funkcionalita (napr. export faktúr)
- UI detaily (umiestnenie tlačidla, názvy)
Manuál má stáť na Core logike, nie na UI detailoch.
5. Nepopisuj konkrétnu obrazovku ako jedinú pravdu
Radšej:
- „v časti Fakturácia“
- „v detaile faktúry“
než:
- „na druhej záložke zľava“
6. Pridaj kontext „čo sa môže zmeniť“
Krátka poznámka pomôže:
Názvy tlačidiel alebo ich umiestnenie sa môžu líšiť podľa verzie.
Znížiš tým falošné očakávania.
Príklad (porovnanie)
Krehký manuál:
Klikni na tretie tlačidlo vpravo hore s názvom Export.
Odolný manuál:
Ako exportovať faktúry do XML
- Otvor Fakturáciu
- Spusť export (funkcia na stiahnutie dát do súboru)
- Vyber rozsah dátumov
- Zvoľ formát XML
- Potvrď export
Výsledok:
Súbor sa stiahne a môžeš ho použiť v účtovníctve.
Mini checklist
- Nie je manuál závislý na presnej polohe prvkov?
- Rozumiem krokom aj bez screenshotu?
- Je jasné, čo jednotlivé kroky robia?
- Je text použiteľný aj po malej UI zmene?
- Stojí manuál na logike, nie na vzhľade?
Prepojenie na kvalitu a workflow
Manuál odolný voči zmenám nevznikne náhodou.
Musí byť súčasťou procesu:
- pri návrhu sa myslí na stabilné pojmy
- tester si všíma, čo je krehké
- dokumentácia sa píše paralelne s vývojom
Ak tím rieši manuál až po release,
je už neskoro.
Vznikne opis konkrétnej verzie, nie použiteľný návod.
Krátke zhrnutie
Manuál, ktorý sa musí prepisovať pri každej verzii, je zle navrhnutý.
Dobrý manuál:
- vysvetľuje význam, nie pozíciu
- vedie používateľa cez úlohu
- stojí na stabilných častiach systému
Ak malá UI zmena rozbije manuál,
manuál bol od začiatku krehký.
A krehká dokumentácia znamená krehký proces.