Čo má a čo nemá obsahovať
Séria: Ako písať dokumentáciu a manuály v IT projekte
Prečo sa v sérii o dokumentácii venujeme user story
Na prvý pohľad to môže vyzerať zvláštne.
Táto séria je o dokumentácii, manuáloch a znalostných bázach.
Prečo teda začíname pri user story?
Pretože práve tu sa často rodí chaos, ktorý sa neskôr objaví v:
- testoch
- používateľských manuáloch
- support dokumentácii
- release notes
Ak je zadanie nejasné už na začiatku, všetky ďalšie vrstvy dokumentácie budú nejasné tiež.
User story je prvý bod, kde sa opisuje správanie systému.
Nie je to ešte špecifikácia, ale je to základ, z ktorého sa neskôr odvodzuje:
User story → Akceptačné kritériá → Test cases → Manuál → Release notes
Ak je prvý krok slabý, celý reťazec sa začne rozpadávať.
Reálny problém z praxe
V mnohých projektoch vyzerá user story takto:
„Je potrebné pridať možnosť exportu údajov.“
To je všetko.
Bez ďalších informácií.
Vývojár potom háda:
- kam sa export pridá
- aké údaje má obsahovať
- v akom formáte
- kto ho môže používať
Tester následne háda:
- čo je vlastne správne správanie
- aké sú výnimky
- čo sa má stať pri chybe
A keď sa neskôr píše dokumentácia, autor manuálu často robí ešte tretí krok:
skúša v systéme, čo to vlastne robí, a podľa toho to opíše.
Čo sa tu vlastne pokazilo
Problém nie je v ľuďoch.
Problém je v tom, že user story je zamieňaná za špecifikáciu.
User story má úplne inú úlohu.
Jej cieľ je povedať:
- prečo funkcionalita existuje
- kto ju potrebuje
- akú hodnotu prináša
Nie je to technický dokument.
Nie je to detailný opis správania systému.
Čo má obsahovať user story
Dobrá user story odpovedá na tri základné otázky.
Kto?
Aký typ používateľa alebo roly.
Čo chce urobiť?
Akú akciu potrebuje vykonať.
Prečo?
Aký problém tým rieši.
Typický tvar:
Ako používateľ chcem exportovať zoznam objednávok, aby som ich mohol spracovať v účtovnom systéme.
To je všetko.
User story nemá obsahovať:
- databázové polia
- API endpointy
- technické riešenie
- implementačné detaily
Tie patria inde.
Čo user story neobsahuje (a kde to má byť)
Práve tu vzniká najviac nedorozumení.
| Typ informácie | Kam patrí |
| hraničné podmienky | akceptačné kritériá |
| výnimky | akceptačné kritériá |
| chybové stavy | akceptačné kritériá / špecifikácia |
| presné správanie systému | špecifikácia |
| technické riešenie | technická dokumentácia |
Ak tieto vrstvy chýbajú, celý tím začne improvizovať.
Skutočné náklady slabej user story
Keď je user story len jedna veta bez ďalších informácií, vzniká typický reťazec problémov:
- Vývojár implementuje riešenie podľa vlastného výkladu.
- Tester testuje podľa vlastného výkladu.
- Používateľ očakáva niečo tretie.
- Dokumentácia opisuje štvrtú verziu reality.
Výsledok:
- zbytočné bugy
- konflikty medzi tímami
- nepresná dokumentácia
- zvýšená závislosť na senioroch
Minimálny model riešenia
User story nemusí byť dlhá.
Stačí, ak má jasnú štruktúru a nadväzujú na ňu ďalšie vrstvy.
- User story
Opis potreby používateľa.
- Akceptačné kritériá
Konkrétne scenáre správania systému.
- Test cases
Overenie správania.
- Dokumentácia
Opis funkcionality pre používateľa.
Tento reťazec je jednoduchý, ale vo firmách často chýba.
Prečo je to dôležité pre dokumentáciu
Dokumentácia sa nepíše z hlavy.
Vzniká z informácií, ktoré už v projekte existujú.
Ak sú user story a akceptačné kritériá kvalitné, dokumentácia sa píše výrazne jednoduchšie.
Autor manuálu nemusí skúšať, „čo to robí“.
Vie:
- čo je cieľ funkcionality
- aké scenáre existujú
- aké sú obmedzenia
Krátke zhrnutie
User story nie je špecifikácia.
Je to opis potreby používateľa.
Ak projekt očakáva, že jedna veta v Jire vysvetlí celé správanie systému, vznikne chaos:
- vývoj háda implementáciu
- tester háda správanie
- dokumentácia opisuje experiment
Dobrá dokumentácia nezačína pri manuáli.
Začína pri dobrom zadaní funkcionality.