Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Na projekte sa pripraví špecifikácia.
Obsahuje:
- vstupy
- výstupy
- chybové stavy
- základné scenáre
Vývoj začne implementovať.
Po čase sa objavia otázky:
- Kde je tlačidlo na spustenie akcie?
- Ako sa zobrazí výsledok?
- Čo používateľ uvidí pri chybe?
- Je to tabuľka, popup alebo len hláška?
Začnú diskusie.
Vývojár navrhne riešenie.
Tester má inú predstavu.
Biznis očakáva niečo tretie.
A tím sa začne dohadovať o veciach, ktoré mali byť vyriešené ešte pred vývojom.
Čo sa tu vlastne pokazilo (analýza systému)
Špecifikácia opisuje správanie systému.
Ale často neobsahuje jednu dôležitú vec:
ako sa toto správanie prejaví pre používateľa.
Chýba prepojenie medzi:
- logikou systému
- a jeho zobrazením
Výsledok:
- systém „funguje“
- ale každý si ho predstavoval inak
UI návrh sa potom rieši:
- počas vývoja
- počas testovania
- alebo až pri písaní manuálu
To je neskoro.
Skutočné náklady (čas, chaos, riziko)
Ak špecifikácia neobsahuje UI návrh:
Vývoj robí rozhodnutia za biznis
- vývojár určuje, ako bude obrazovka vyzerať
Tester nemá čo porovnať
- nevie, či je UI správne, len či „funguje“
Vznikajú nekonečné diskusie
- „takto sme to nemysleli“
- „ale nikde to nebolo napísané“
Manuál sa píše spätne
- opisuje realitu, nie zámer
A tím stráca čas na veciach, ktoré mali byť jasné na začiatku.
Minimálny model riešenia
UI návrh nemusí byť dizajnérsky dokument.
Stačí jednoduchý, ale jasný opis toho, čo používateľ uvidí.
Minimálne by mal obsahovať:
Rozloženie (layout)
- kde sa nachádzajú prvky
- čo je tlačidlo, čo je pole, čo je tabuľka
Zoznam prvkov
- aké komponenty sú na obrazovke
- názvy tlačidiel, polí, sekcií
Správanie prvkov
- čo sa stane po kliknutí
- čo sa zobrazí pri chybe
- čo sa zobrazí pri úspechu
Výsledok pre používateľa
- kde sa zobrazí výsledok
- v akej forme (hláška, tabuľka, export, zmena stavu)
Príklad
Špecifikácia obsahuje vetu:
„Používateľ môže exportovať údaje.“
To nestačí.
Doplnená verzia:
- Na obrazovke je tlačidlo „Export“
- Po kliknutí sa zobrazí výber formátu (CSV, XML)
- Po potvrdení sa súbor stiahne
- Ak nie sú dáta, zobrazí sa hláška „Nie sú dostupné údaje na export“
Zrazu:
- vývoj vie, čo implementovať
- tester vie, čo testovať
- dokumentácia má z čoho vychádzať
Mini checklist
Pri čítaní špecifikácie by si tím mal vedieť odpovedať:
- Je jasné, čo používateľ uvidí?
- Je jasné, kde sa to zobrazí?
- Sú definované všetky prvky na obrazovke?
- Je popísané správanie po akcii?
- Sú definované chybové hlášky?
Ak nie, špecifikácia nie je kompletná.
Prepojenie na kvalitu a workflow
Špecifikácia je začiatok reťazca:
User story → Špecifikácia → Test → Manuál → Release
UI návrh je most medzi:
- špecifikáciou
- a reálnym použitím systému
Ak chýba:
- testovanie sa mení na hádanie
- dokumentácia sa píše spätne
- používateľ dostane iný výsledok, než očakával
Ako testerka často vidím, že najväčšie problémy nevznikajú v logike.
Vznikajú v tom, že:
nikto presne nepovedal, čo má používateľ vidieť.
Krátke zhrnutie
Špecifikácia bez UI návrhu nie je kompletná.
Nie preto, že by chýbal dizajn.
Ale preto, že chýba definícia výsledku pre používateľa.
Ak nie je jasné, čo používateľ uvidí:
- vývoj rozhoduje namiesto biznisu
- tester nemá čo overiť
- dokumentácia opisuje náhodnú realitu
Dobrá špecifikácia nehovorí len, čo systém robí.
Hovorí aj to, ako sa to prejaví navonok.