Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
V projekte pribudne nová funkcionalita.
V Jire existuje Epic, niekoľko user story a pár taskov. Vývoj prebehne, tester pripraví testy a funkcionalita sa nasadí do produkcie.
Potom príde moment, keď treba pripraviť:
- text do používateľského manuálu
- informáciu pre support
- release notes k novej verzii
A tím začne hľadať, kde vlastne je napísané:
- čo mala funkcionalita robiť
- pre koho bola určená
- aké sú výnimky
- čo sa v systéme zmenilo
Časť informácií je v user story.
Časť v taskoch.
Niečo v komentároch.
Niečo si pamätá vývojár.
A človek, ktorý píše dokumentáciu, nakoniec skúša systém a opisuje, čo vidí.
Dokumentácia tak nevzniká zo zadania.
Vzniká z dohľadávania informácií.
Čo sa tu vlastne pokazilo (analýza systému)
Problém väčšinou nie je v nástroji.
Jira môže fungovať veľmi dobre – ak je jasné, aký typ informácie patrí do ktorého typu issue.
V projektoch sa však často miešajú štyri rôzne vrstvy:
- biznis cieľ funkcionality
- očakávané správanie systému
- technická implementácia
- reálne chyby
Keď sa tieto vrstvy premiešajú, prestane fungovať tok informácií v projekte.
V praxi by mali mať jednotlivé typy issue približne tieto úlohy.
| Typ v Jire | Úloha v projekte |
| Epic | väčší biznis celok alebo oblasť produktu |
| User story | potreba používateľa a biznis význam funkcionality; obsahuje aj akceptačné kritériá, ktoré opisujú očakávané správanie systému |
| Task | technické alebo analytické kroky implementácie |
| Bug | odchýlka medzi očakávaným a reálnym správaním |
Dôležitá vec: akceptačné kritériá nie sú samostatný typ issue v Jire.
Patria priamo do user story – zvyčajne do popisu alebo do samostatnej sekcie „Acceptance criteria“.
Práve akceptačné kritériá opisujú:
- ako sa má systém správať
- aké sú výnimky
- kedy je funkcionalita považovaná za hotovú
A z tejto vrstvy sa potom pripravujú:
- test cases
- text v používateľskom manuáli
- stručný opis zmeny v release notes
Skutočné náklady (čas, chaos, riziko)
Keď nie je jasné, kam čo zapisovať, vznikajú veľmi konkrétne problémy.
Prvým je strata času.
Tím neustále dohľadáva, kde je vlastne popísané správanie systému.
Druhým je nekonzistentnosť.
Tester vychádza z jednej interpretácie, dokumentácia z druhej a release notes z tretej.
Tretím je závislosť na konkrétnych ľuďoch.
Ak niekto odíde z projektu, časť znalostí odchádza s ním.
Štvrtým je problém pri podpore zákazníkov.
Support nevie, čo je štandardné správanie systému a čo je výnimka.
A piatym je komplikované zavádzanie AI alebo outsourcingu podpory.
Ak sú informácie roztrúsené v rôznych issue a komentároch, nevzniká spoľahlivý zdroj znalostí.
Minimálny model riešenia
Stačí jednoduché pravidlo: každá vrstva informácií má svoje miesto.
Epic – širší kontext
Epic opisuje väčší celok v produkte.
Príklad:
Epic: Správa objednávok
Epic vysvetľuje, akú oblasť produktu riešime a prečo existuje.
User story – biznis potreba a správanie systému
User story opisuje potrebu používateľa a hodnotu funkcionality.
Príklad:
Ako účtovníčka chcem exportovať objednávky, aby som ich mohla spracovať v účtovnom systéme.
Súčasťou user story sú akceptačné kritériá, ktoré opisujú správanie systému.
Napríklad:
- export je dostupný len pre rolu Účtovník
- po kliknutí na Export sa stiahne CSV súbor
- ak je zoznam prázdny, export sa nevykoná a zobrazí sa hlásenie
Toto je vrstva, z ktorej sa pripravujú testy aj dokumentácia.
Task – implementácia
Task obsahuje technické alebo analytické kroky.
Napríklad:
- vytvoriť exportný endpoint
- upraviť generovanie CSV
- doplniť validáciu oprávnení
- pripraviť test data
Task rieši ako funkcionalita vznikne, nie čo má systém robiť.
Bug – odchýlka od očakávania
Bug vzniká vtedy, keď sa reálne správanie systému líši od akceptačných kritérií.
Obsahuje napríklad:
- kroky na reprodukciu
- reálne správanie
- očakávané správanie
- verziu prostredia
Bug nie je náhrada za chýbajúce akceptačné kritériá.
Označenie verzie v Jire
Aby bolo možné pripraviť release notes a dokumentáciu bez dohľadávania v histórii, všetky issue by mali mať priradenú verziu.
V Jire na to slúži pole Fix Version / Version.
Toto pole určuje, v ktorej verzii produktu sa zmena objaví.
Ak je verzia správne vyplnená, dá sa jednoducho vyselektovať všetko, čo patrí do konkrétneho release.
Napríklad pre verziu 2.5 je možné jedným filtrom zobraziť:
- nové user story
- opravené bugy
- zmeny vo funkcionalite
Práve z tohto zoznamu potom vznikajú:
- release notes
- prehľad zmien pre zákazníkov
- podklady pre aktualizáciu dokumentácie
Ak issue nemajú označenie verzie, tím musí pri každom release ručne dohľadávať, čo sa vlastne zmenilo.
Tok informácií v projekte
Ak sú tieto vrstvy oddelené, vzniká prirodzený tok informácií:
Epic → User story (s akceptačnými kritériami) → Tasky / Test cases → Bugy → Dokumentácia / Release notes
User story dáva kontext.
Akceptačné kritériá definujú správanie systému.
Tasky riešia implementáciu.
Bugy zachytávajú odchýlky.
Prepojenie na kvalitu a workflow
Toto rozdelenie nie je len organizačná pomôcka.
Má priamy dopad na kvalitu práce v tíme.
Tester vie pripraviť testy bez dohadovania.
Autor dokumentácie vie, čo má opísať.
Support rozumie správaniu systému.
Release notes nevznikajú na poslednú chvíľu z pamäti vývojára.
A zároveň vzniká základ pre ďalšie škálovanie projektu – napríklad pre znalostnú bázu, interného AI asistenta alebo outsourcovanú zákaznícku podporu.
Krátke zhrnutie
User story opisuje prečo a pre koho funkcionalita vzniká.
Akceptačné kritériá (ktoré sú súčasťou user story) opisujú ako sa má systém správať.
Tasky riešia technickú implementáciu.
Bugy zachytávajú odchýlky medzi očakávaním a realitou.
A označenie verzie v Jire umožňuje jednoducho zistiť, ktoré zmeny patria do konkrétneho release.
Keď je tento model v Jire dodržaný, dá sa z jedného zadania prirodzene vytvoriť:
- testovanie
- dokumentácia
- aj zrozumiteľné release notes.