Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Support rieši problém:
„Export padá pri väčšom objeme dát.“
V Jire existuje bug:
- popis chyby
- kroky na reprodukciu
- technické detaily
Bug sa opraví.
Ticket sa uzavrie.
A tým to končí.
O pár dní príde rovnaký problém na support.
A support nevie, že:
- chyba už existovala
- existuje riešenie
- existujú podmienky, kedy vzniká
Čo sa tu vlastne pokazilo (analýza systému)
Bug report existuje.
Ale nie je prepojený so support dokumentáciou.
Typická realita:
- bug je napísaný pre vývoj
- obsahuje technické detaily
- nie je použiteľný pre support
A zároveň:
- support dokumentácia nevznikne
Výsledok:
- informácia existuje
- ale nedá sa použiť v praxi
Bug report je zdroj pravdy.
Ale nie je to hotová dokumentácia.
Skutočné náklady (čas, chaos, riziko)
Ak sa bug reporty nevyužívajú:
- support rieši známe problémy od nuly
- vznikajú zbytočné eskalácie
- tím opakovane analyzuje to isté
Vznikajú aj ďalšie problémy:
- support nevie rozlíšiť bug vs konfigurácia
- klient dostáva nekonzistentné odpovede
- znalosti sú roztrúsené medzi nástrojmi
Minimálny model riešenia
Základná zmena:
Bug report nie je koniec. Je to vstup do dokumentácie.
Ako premeniť bug report na support položku
Bug report obsahuje:
- kroky na reprodukciu
- očakávané správanie
- reálne správanie
- technické údaje
Z toho vznikne support položka:
- Symptóm
„Export padá pri veľkom objeme dát“ - Príčina
limit v spracovaní - Diagnostika
aké dáta problém spôsobujú
kde to overiť - Riešenie
workaround alebo fix - Eskalácia
kedy to ide na vývoj
Čo je dôležité
- preložiť technický jazyk na support jazyk
- zamerať sa na symptóm, nie implementáciu
- doplniť kontext (kedy sa to stane)
- odstrániť zbytočné detaily
Príklad z praxe
Bug report:
- chyba pri spracovaní XML nad 10 000 záznamov
- stack trace
- detail implementácie
Support položka:
Symptóm:
Export sa zastaví pri veľkom objeme dát
Príčina:
limit spracovania
Diagnostika:
over počet záznamov
Riešenie:
rozdeliť export alebo použiť fix
Prepojenie na kvalitu a workflow
Bug report by nemal skončiť „Done“.
Mal by mať pokračovanie:
- oprava chyby
- aktualizácia dokumentácie
Ideálne ako súčasť Definition of Done:
- existuje support položka pre opravený bug (ak relevantné)
Tým sa:
- znižuje opakovanie problémov
- zlepšuje komunikácia
- zrýchľuje support
Krátke zhrnutie
Bug report obsahuje riešenie problému.
Support dokumentácia umožňuje toto riešenie použiť.
Ak sa bug report nepretransformuje:
- informácia ostane v Jire
- support ju nevyužije
Ak sa pretransformuje:
- vzniká znalostná báza
- tím sa učí
- problémy sa neopakujú
Bug report nie je len vstup pre vývoj.
Je to zdroj pre celý tím.