Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Tím rieši incident:
- problém sa analyzuje
- nájde sa príčina
- opraví sa
Ticket sa uzavrie.
O pár dní príde rovnaký problém.
A nikto nevie, že už bol vyriešený.
Support dokumentácia existuje, ale:
- je neúplná
- je zastaraná
- alebo vzniká náhodne
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v tom, že tím nevie písať dokumentáciu.
Problém je, že neexistuje pravidlo, kedy má vzniknúť.
Realita vo firmách:
- dokumentácia sa píše „keď je čas“
- nikto za ňu nemá zodpovednosť
- nie je súčasť workflow
Výsledok:
- znalosti ostávajú v hlavách
- incidenty sa opakujú
- dokumentácia zaostáva za realitou
Dokumentácia nie je súčasť procesu.
Je vedľajší produkt.
Skutočné náklady (čas, chaos, riziko)
Ak dokumentácia nevzniká systematicky:
- každý incident sa rieši od nuly
- support závisí na senioroch
- onboarding je pomalý
- odpovede klientom sú nekonzistentné
Vznikajú aj skryté náklady:
- zbytočné eskalácie
- falošné bugy
- strata dôvery v dokumentáciu
Tím síce pracuje, ale znalosti sa neakumulujú.
Minimálny model riešenia
Základná zmena:
Support dokumentácia musí byť súčasť workflow.
Nie „keď si spomenieme“.
Ale ako povinný krok.
Kedy má vzniknúť support dokumentácia
Minimálne v týchto situáciách:
- nový incident v produkcii
- opravený bug
- nová funkcionalita
- zmena správania systému
Ako to zapracovať do procesu
1. Incident workflow
- incident vyriešený
- vzniká support položka
Bez zápisu → incident nie je „hotový“
2. Bug workflow
- bug opravený
- doplniť dokumentáciu
Najmä ak:
- bol nejasný symptóm
- problém sa opakoval
3. Vývoj (feature)
- nová funkcionalita
- pripraviť support scenáre
Nie len „ako to funguje“, ale:
- čo sa pokazí
- ako to support rozpozná
Definition of Done (DoD)
Kľúčový moment.
Support dokumentácia musí byť súčasť DoD.
Príklad formulácie do DoD
- existuje support položka pre novú funkcionalitu
- existuje dokumentácia k opravenému bugu (ak relevantné)
- diagnostika je popísaná
- je jasné, kedy eskalovať
Príklad z praxe
Bug:
Export padá na konkrétnom type dát
Riešenie:
- opravený kód
Bez DoD:
- dokumentácia nevznikne
- support o tom nevie
S DoD:
- vznikne support položka
- ďalší incident sa vyrieši rýchlo
Rozdiel nie je v technickom riešení.
Je v procese.
Prepojenie na kvalitu a workflow
Toto je bod, kde sa dokumentácia mení na nástroj kvality.
Ak je súčasťou workflow:
- znalosti sa ukladajú systematicky
- support sa zrýchľuje
- znižuje sa závislosť na senioroch
Ak nie je:
- tím funguje na pamäti jednotlivcov
A to sa nedá škálovať.
Krátke zhrnutie
Support dokumentácia nevzniká písaním.
Vzniká procesom.
Kľúčová otázka nie je:
„Ako ju napísať?“
Ale:
„Kedy je povinné ju vytvoriť?“
Ak to nie je súčasť workflow a Definition of Done:
- dokumentácia bude vždy pozadu
- incidenty sa budú opakovať
Dokumentácia je výsledok disciplíny tímu, nie dobrej vôle.