Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Na projekte sa objaví nové zadanie.
User story má tri vety.
Akceptačné kritériá sú dve odrážky.
„Treba pridať export údajov.“
Vývojár sa opýta analytika, ako to má fungovať.
Tester sa opýta vývojára, čo vlastne implementoval.
A keď sa začne písať dokumentácia, autor skúša funkcionalitu priamo v systéme, aby zistil, čo robí.
Každý sa snaží problém vyriešiť.
Ale každý pracuje s inou predstavou o tom, ako sa má systém správať.
Problém nie je v ľuďoch.
Problém je v špecifikácii.
Čo sa tu vlastne pokazilo (analýza systému)
Veľa tímov zamieňa tri rôzne veci:
- user story
- akceptačné kritériá
- špecifikáciu
User story vysvetľuje prečo funkcionalita existuje.
Akceptačné kritériá definujú čo musí systém splniť.
Špecifikácia opisuje ako sa má systém správať v detailoch.
Ak sa špecifikácia vynechá, vzniknú rôzne interpretácie:
- vývoj implementuje podľa vlastného pochopenia
- tester testuje podľa svojho
- používateľ očakáva niečo tretie
Dokumentácia potom opisuje systém tak, ako sa nakoniec správa – nie tak, ako mal byť navrhnutý.
Skutočné náklady (čas, chaos, riziko)
Nejasná špecifikácia má konkrétne dopady:
- opakované otázky počas vývoja
- neúplné alebo nesprávne test cases
- falošné bugy
- zbytočné úpravy implementácie
- nepresná dokumentácia
A často aj konflikty medzi tímami.
Vývoj tvrdí: „Takto to bolo zadané.“
Tester tvrdí: „Takto to malo fungovať.“
Používateľ tvrdí: „Ja som čakal niečo iné.“
Minimálny model riešenia
Testovateľná špecifikácia nemusí byť dlhý dokument.
Musí však obsahovať základné informácie, ktoré umožnia pochopiť správanie systému.
- Kontext
- Prečo funkcionalita vzniká
- Scenár použitia
- Kto a v akej situácii ju používa
- Vstupy
- Aké údaje systém prijíma
- Spracovanie
- Čo systém s údajmi robí
- Výstupy
- Aký je výsledok operácie
- čo systém zobrazí používateľovi (UI, obrazovka, hláška, tabuľka)
- v akej forme používateľ výsledok uvidí alebo dostane (UI / export / API)
- Chybové stavy
- Čo sa stane pri probléme
- akú chybu používateľ uvidí a kde sa zobrazí
- Obmedzenia
- Čo systém nerobí
Ak tieto informácie existujú, tester vie pripraviť test cases bez dodatočných otázok.
Mini checklist testovateľnej špecifikácie
Pred začiatkom vývoja by sa mal tím vedieť opýtať:
- Sú definované vstupy do systému?
- Sú definované výstupy?
- Je jasné, čo používateľ uvidí na obrazovke?
- Sú uvedené chybové stavy?
- Sú popísané hraničné situácie?
- Je jasné, čo funkcionalita nerieši?
Ak odpoveď na niektorú otázku chýba, špecifikácia ešte nie je pripravená.
Prepojenie na kvalitu a workflow
V projekte existuje prirodzený reťazec:
User story → Akceptačné kritériá → Špecifikácia → Test cases → Dokumentácia
Ak je špecifikácia nejasná, chaos sa prenesie do všetkých ďalších krokov.
Tester potom netestuje len softvér.
Testuje aj interpretáciu zadania.
A dokumentácia vzniká spätne – podľa toho, čo sa nakoniec implementovalo.
Ak však nie je jasné:
- čo má používateľ vidieť
- kde sa to má zobraziť
- aké prvky má mať obrazovka
testovanie sa mení na kontrolu „či niečo funguje“, nie „či je to správne“.
Krátke zhrnutie
Testovateľná špecifikácia nie je byrokracia.
Je to nástroj, ktorý umožňuje tímu pochopiť správanie systému ešte pred vývojom.
Ak tester dokáže podľa špecifikácie pripraviť test cases bez dodatočných otázok, špecifikácia je pravdepodobne dobrá.
A ak je jasné aj to, čo používateľ uvidí, tím pracuje s rovnakou predstavou o výsledku.
Ak nie, problém nevznikne až pri testovaní.
Vznikol už pri zadaní funkcionality.