Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Support otvorí dokumentáciu.
Nájde riešenie.
Postupuje podľa neho.
Nefunguje.
Po chvíli zisťuje:
- postup je zastaraný
- systém sa medzitým zmenil
- workaround už neplatí
A ide sa pýtať kolegu.
Čo sa tu vlastne pokazilo (analýza systému)
Dokumentácia existuje.
Ale nie je aktuálna.
Typická realita:
- články vzniknú
- nikto ich už neudržiava
- zmeny v systéme sa do nich nepremietnu
Výsledok:
- dokumentácia zaostáva za realitou
- stráca dôveru
A keď support prestane veriť dokumentácii,
prestane ju používať.
Skutočné náklady (čas, chaos, riziko)
Zastaraná dokumentácia je horšia než žiadna:
- support robí podľa nesprávnych postupov
- vznikajú nové chyby
- riešenie incidentov sa spomaľuje
Ďalšie dôsledky:
- nekonzistentné odpovede klientom
- zbytočné eskalácie
- strata času pri overovaní
A hlavne:
tím začne dokumentáciu obchádzať.
Minimálny model riešenia
Základ:
Dokumentácia musí mať životný cyklus.
Nie je to jednorazový výstup.
1. Verziovanie
Každá položka má obsahovať:
- verziu systému
- dátum poslednej aktualizácie
Príklad:
- „Platí od verzie 3.2“
- „Aktualizované: 03/2026“
2. Prepojenie na zmeny
Každá zmena v systéme musí mať dopad na dokumentáciu:
- nový feature → nová položka
- zmena správania → aktualizácia
- fix bugu → úprava riešenia
Bez tohto prepojenia:
- dokumentácia zastaráva automaticky
3. Označenie zastaraných riešení
Nie všetko treba hneď mazať.
Ale treba označiť:
- „zastarané“
- „neplatné od verzie X“
Support musí vedieť:
- že riešenie už neplatí
4. Archivácia
Staré riešenia majú hodnotu:
- historické incidenty
- staršie verzie systému
Preto:
- nevymazávať
- presunúť do archívu
Výsledok:
- aktuálna časť je čistá
- historická je dostupná
5. Workaroundy a ich životný cyklus
Najčastejší problém:
- workaround zostane aj po fixe
Riešenie:
- prepojiť workaround s bugom
- po oprave bugu ho odstrániť alebo označiť
Príklad z praxe
Bug:
Export padá pri veľkých dátach
Workaround:
rozdeliť export
Po fixe:
- workaround už neplatí
Ak sa neodstráni:
- support ho používa ďalej
- klient dostáva zbytočne komplikované riešenie
Prepojenie na workflow
Aktualizácia dokumentácie musí byť súčasť procesu:
- release → kontrola dokumentácie
- bug fix → aktualizácia riešenia
- incident → nový zápis
Bez toho:
- dokumentácia vždy zaostáva
Prepojenie na kvalitu
Aktuálnosť dokumentácie priamo ovplyvňuje:
- rýchlosť supportu
- kvalitu odpovedí
- dôveru tímu
A zároveň:
je základ pre AI a automatizáciu.
AI nad zastaranými dátami = nesprávne odpovede.
Krátke zhrnutie
Dokumentácia nie je statická.
Ak sa neudržiava:
- zastaráva
- stráca dôveru
- prestáva sa používať
Základ:
- verziovanie
- aktualizácie pri zmene
- označenie zastaraných riešení
- archivácia
Ak dokumentácia neodráža realitu systému,
ako keby neexistovala.