Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Tím má:
- user story
- akceptačné kritériá
- špecifikáciu
- bugy
Support má:
- otázky od používateľov
Medzi tým nie je prepojenie.
Výsledok:
- support nevie, čo systém robí
- nevie, čo je chyba
- nevie, čo je očakávané správanie
Dokumentácia existuje, ale nie je napojená na realitu.
Čo sa tu vlastne pokazilo (analýza systému)
Artefakty existujú.
Ale nie sú prepojené:
- user story je v Jire
- špecifikácia inde
- bugy inde
- dokumentácia inde
Support potrebuje:
- konkrétne riešenie problému
Nie:
- roztrúsené informácie
Skutočné náklady (čas, chaos, riziko)
Bez prepojenia:
- support sa pýta vývoja
- vznikajú falošné bugy
- rovnaké problémy sa riešia opakovane
A hlavne:
znalosti sa neprenášajú do dokumentácie.
Minimálny model riešenia
Základ:
Každý reálny scenár pretransformovať do support položky.
Zdroje:
- user story
- akceptačné kritériá
- špecifikácia
- bugy
- incidenty
Výstup:
- jedna konkrétna support položka
Príklad 1: Prihlásenie používateľa
User story
Ako používateľ sa chcem prihlásiť do systému, aby som mohol pracovať s aplikáciou.
Akceptačné kritériá
- správne údaje → prihlásenie úspešné
- nesprávne údaje → chyba
- zablokovaný účet → prihlásenie zablokované
Bug
Používateľ s blokovaným účtom dostane nejasnú chybu.
Support položka
Názov:
Používateľ sa nevie prihlásiť
Možné príčiny:
- nesprávne heslo
- zablokovaný účet
- chýbajúca rola
Diagnostika:
- over login
- skontroluj stav účtu
- pozri log autentifikácie
Riešenie:
- reset hesla
- odblokovanie účtu
Príklad 2: Export dát
User story
Ako používateľ chcem exportovať dáta do XML.
Akceptačné kritériá
- export sa spustí
- export obsahuje všetky dáta
Bug
Export padá pri veľkom objeme dát.
Support položka
Názov:
Export padá pri veľkom objeme dát
Možné príčiny:
- limit spracovania
Diagnostika:
- over počet záznamov
- pozri log exportu
Riešenie:
- rozdeliť export
Workaround:
- dočasné riešenie do fixu
Príklad 3: Vytvorenie faktúry
User story
Ako používateľ chcem vytvoriť faktúru.
Akceptačné kritériá
- faktúra sa uloží
- obsahuje všetky povinné údaje
Incident
Faktúra sa nevytvorí.
Support položka
Názov:
Faktúra sa nevytvorí
Možné príčiny:
- chýbajúce údaje
- nesprávna konfigurácia
Diagnostika:
- over povinné polia
- skontroluj nastavenia
Riešenie:
- doplniť údaje
- opraviť konfiguráciu
Príklad 4: Klientská úprava (Core vs Custom)
Špecifikácia
Pre klienta XY je upravený export.
Problém
Iný klient očakáva rovnaké správanie.
Support položka
Názov:
Export obsahuje špecifické pole
Príčina:
Custom úprava pre klienta XY
Diagnostika:
- over klienta
- over konfiguráciu
Riešenie:
- vysvetliť rozdiel
- neeskalovať ako bug
Prepojenie na kvalitu a workflow
Tieto scenáre ukazujú:
- ako sa informácie transformujú
- ako vzniká dokumentácia
- ako sa prepája vývoj a support
Ak tento krok neexistuje:
- dokumentácia nevzniká
- support funguje izolovane
Krátke zhrnutie
User story, špecifikácia a bugy sú vstupy.
Support dokumentácia je výstup.
Ak medzi nimi nie je prepojenie:
- tím nefunguje ako systém
Každý reálny problém má skončiť ako:
- konkrétna support položka
To je moment, kde sa z projektu stáva riadený systém.