Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Admin rieši incident v produkcii.
Nevie:
- kde nájsť logy
- aké zmeny boli nasadené
- či je problém v konfigurácii alebo v kóde
Otvorí administrátorský manuál.
Nájde:
- všeobecný popis systému
- zoznam funkcií
- pár screenshotov
Nenájde:
- postup riešenia
- hranice systému
- reálne prevádzkové scenáre
Volá vývojára.
Čo sa tu vlastne pokazilo (analýza systému)
Administrátorská príručka neplní svoj účel.
Typické chyby:
- opis systému namiesto riadenia prevádzky
- miešanie cieľových skupín
- chýbajúce prevádzkové scenáre
- neaktuálne alebo neúplné informácie
Dokumentácia existuje, ale nedá sa podľa nej pracovať.
To je systémové zlyhanie.
Skutočné náklady (čas, chaos, riziko)
Dopady v praxi:
- závislosť na senioroch
- pomalé riešenie incidentov
- chybné nasadenia
- konflikty medzi tímami
Typický vzorec:
Admin nevie → kontaktuje support → support eskaluje → vývoj rieši
Dokumentácia sa obchádza.
Minimálny model riešenia
Administrátorská príručka musí byť navrhnutá pre reálnu prácu admina.
Nie pre audit. Nie pre „aby niečo bolo“.
Chyba 1: Opis funkcionality namiesto dopadov
Zlá prax:
„Systém umožňuje nastaviť parameter X.“
Chýba:
- čo sa stane pri zmene
- aké sú riziká
- čo to ovplyvní
Správny prístup:
„Zmena parametra X ovplyvní modul Y.
Pri nesprávnom nastavení môže dôjsť k…“
Chyba 2: Chýbajúce prevádzkové scenáre
V dokumentácii nie je:
- čo robiť pri výpadku
- ako riešiť chyby
- ako postupovať pri upgrade
Admin má informácie, ale nemá postup.
Chyba 3: Miešanie rolí
V jednom dokumente je:
- infra admin
- aplikačný admin
- biznis admin
Každý potrebuje niečo iné.
Výsledok:
Nikto si nie je istý, čo sa ho týka.
Chyba 4: Nejasné hranice systému
Nie je definované:
- čo rieši aplikácia
- čo rieši infraštruktúra
- čo rieši externý systém
Výsledok:
Incidenty sa presúvajú medzi tímami.
Chyba 5: Chýbajú upgrade a rollback postupy
Dokumentácia obsahuje:
- ako systém funguje
Neobsahuje:
- ako ho nasadiť
- ako ho vrátiť späť
Toto je kritická medzera.
Chyba 6: Neaktuálne informácie
Dokumentácia:
- neobsahuje verziu
- neodráža posledný release
- obsahuje neplatné kroky
Admin postupuje správne podľa dokumentácie.
A napriek tomu zlyhá.
Chyba 7: Core vs Custom nie je oddelené
Nie je jasné:
- čo je súčasť produktu
- čo je klientská úprava
Dopad:
- tester hlási falošné bugy
- support sľubuje neexistujúce funkcionality
- onboarding trvá dlhšie
Toto je častý zdroj chaosu v produktoch.
Prepojenie na kvalitu a workflow
Administrátorská dokumentácia je súčasť workflow:
Feature → Test → Dokumentácia → Release → Prevádzka
Ak dokumentácia zlyhá:
- testovanie neoverí reálne scenáre
- release nie je kontrolovaný
- prevádzka improvizuje
Dokumentácia nie je výstup.
Je kontrolný mechanizmus kvality.
Krátke zhrnutie
Najčastejšie chyby v admin príručkách:
- opis namiesto dopadov
- chýbajúce scenáre
- miešanie rolí
- nejasné hranice systému
- chýbajúci upgrade a rollback
- neaktuálnosť
- neoddelené core a custom
Ak sa podľa dokumentácie nedá pracovať bez telefonátu seniorovi, dokumentácia zlyháva.
A projekt platí za tento dlh pri každom incidente.