Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
V produkcii vznikne problém:
„Export padá pri veľkom objeme dát.“
Riešenie zatiaľ neexistuje.
Vývoj pripraví workaround:
- rozdeliť export na menšie časti
Support to začne používať.
Klientom to funguje.
O pár mesiacov:
- workaround sa používa ako štandard
- nikto nevie, že ide o dočasné riešenie
- bug sa už nerieši
Čo sa tu vlastne pokazilo (analýza systému)
Workaround vznikol správne.
Chyba bola v tom, že:
- nebol označený ako dočasný
- nebol prepojený s bugom
- nebolo jasné, dokedy platí
Dokumentácia z neho spravila:
- „oficiálny postup“
Toto je jeden z najnebezpečnejších efektov support dokumentácie.
Skutočné náklady (čas, chaos, riziko)
Ak workaroundy nie sú správne zapísané:
- prežijú dlhšie než samotné bugy
- deformujú produktové správanie
- vznikajú nekonzistentné procesy
Ďalšie dôsledky:
- klient dostáva obchádzku namiesto riešenia
- vývoj stráca prioritu opravy
- nový človek nevie, čo je správne správanie
A najhoršie:
nikto nevie, čo je Core a čo je improvizácia.
Minimálny model riešenia
Základné pravidlo:
Workaround musí byť jasne označený ako dočasný.
Čo je workaround
- obchádzka problému
- nie je finálne riešenie
- má obmedzenia
- má časovú platnosť
Ako ho zapisovať v dokumentácii
Každý workaround musí obsahovať:
- označenie
„Dočasné riešenie“ / „Workaround“ - kontext
aký problém rieši - obmedzenia
kedy funguje a kedy nie - prepojenie
link na bug alebo incident - stav
či je fix plánovaný
Príklad z praxe
Symptóm:
Export padá pri veľkom objeme dát
Riešenie:
rozdeliť export
Správny zápis:
- označenie: Workaround
- obmedzenie: nefunguje pri automatizovanom spracovaní
- prepojenie: BUG-123
- poznámka: fix plánovaný
Typické chyby v praxi
- workaround nie je označený
- nie je jasné, že ide o dočasné riešenie
- chýba prepojenie na bug
- chýba informácia o obmedzeniach
Výsledok:
- workaround sa stane štandardom
Prepojenie na dokumentáciu
Workaroundy musia byť oddelené od Core riešení.
Inak:
- support nevie, čo je správny postup
- klient dostáva nekonzistentné informácie
Zároveň musia byť:
- dohľadateľné
- aktualizované
- odstránené po fixe
Prepojenie na kvalitu a workflow
Workaround nie je len technické riešenie.
Je to:
- signál problému
- dočasný stav systému
Preto musí byť súčasťou procesu:
- vznik workaroundu → zápis do dokumentácie
- oprava bug → odstránenie workaroundu
Ak druhý krok neexistuje:
- workaround zostáva navždy
Krátke zhrnutie
Workaround je potrebný.
Ale je nebezpečný.
Ak nie je správne zapísaný:
- stane sa z neho štandard
- deformuje produkt
- zakrýva problémy
Správny workaround:
- je označený
- má obmedzenia
- je prepojený na bug
- má jasný status
Workaround nie je riešenie.
Je to dočasná dohoda s problémom.