Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
V projekte sme mali „manuál“.
Volal sa rovnako pre všetkých – manuál.
Používateľ v ňom hľadal, čo má kliknúť.
Admin v ňom hľadal, ako nastaviť systém.
Support v ňom hľadal, prečo to nefunguje.
Výsledok?
Nikto v ňom nenašiel to, čo potreboval.
A keď prišiel problém, bola tam veta:
„Kontaktujte podporu.“
Lenže support sa pýtal admina.
Admin sa pýtal vývojára.
A vývojár mal odpoveď v hlave.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v tom, že dokumentácia neexistuje.
Problém je, že je zmiešaná.
Zmiešali sa tri rôzne svety:
| Typ dokumentácie | Otázka, ktorú rieši | Pre koho |
| Používateľský manuál | „Čo mám urobiť?“ | koncový používateľ |
| Administrátorská príručka | „Čo sa stane, keď to nastavím?“ | admin |
| Support dokumentácia | „Prečo to nefunguje?“ | podpora |
Administrátorská príručka má úplne iný cieľ než user manuál:
- rieši konfiguráciu
- rieši oprávnenia
- rieši dopady zmien
- rieši integrácie a závislosti
- rieši prevádzku a incidenty
Používateľ toto nepotrebuje.
Admin bez toho nevie fungovať.
Ak to spojíš do jedného textu, stratí sa cieľová skupina.
Skutočné náklady (čas, chaos, riziko)
Keď admin príručka neexistuje (alebo je zamaskovaná ako user manuál):
- onboarding nového admina trvá násobne dlhšie
- konfigurácie sa robia pokus-omyl
- vznikajú bezpečnostné chyby
- upgrade sa robí „na istotu večer a s modlitbou“
- firma je závislá na jednom človeku
A najhoršie:
➡️ chyby sa tvária ako bugy, ale sú to zlé nastavenia
To je čistý testerský problém – falošné bugy.
Minimálny model riešenia
Nepotrebuješ 200-stranový dokument.
Stačí oddeliť veci, ktoré majú byť oddelené.
Základný model:
- Používateľský manuál
- scenáre („ako vytvoriť…“)
- jednoduchý jazyk
- bez technických detailov
- Administrátorská príručka
Musí obsahovať minimálne:
- Roly a oprávnenia
- Konfiguráciu a jej dopady
- Integrácie
- Systémové požiadavky (HW/SW)
- Logovanie a diagnostiku
- Upgrade a rollback
- Known limitations
- Support dokumentácia (oddelene)
- symptóm → príčina → riešenie
Príklad rozdielu (jedna funkcionalita)
User manuál:
Kliknite na „Export“ a vyberte formát.
Admin príručka:
Export je dostupný len pri zapnutej konfigurácii EXPORT_ENABLED=true.
Pri vypnutí sa tlačidlo nezobrazí.
To je zásadný rozdiel v úrovni informácie.
Mini checklist (rýchla kontrola)
Ak si chceš overiť, či máš admin príručku alebo len „prezlečený user manuál“:
- Je jasné, kto je cieľová skupina?
- Obsahuje dokument dopady nastavení?
- Vie admin podľa toho spraviť upgrade?
- Vie admin riešiť incident bez telefonátu?
- Sú uvedené obmedzenia systému?
Ak nie → nie je to admin príručka.
Prepojenie na kvalitu a workflow
Administrátorská príručka nie je „nice to have“.
Je to súčasť kvality produktu.
Bez nej:
- testovanie nevie, čo je konfigurácia vs bug
- support nevie diagnostikovať problém
- onboarding je závislý na senioroch
- release je riziko
A hlavne:
- dokumentácia prestáva byť kontrolný mechanizmus kvality
Ak admin nevie podľa dokumentácie pracovať bez otázok, dokumentácia zlyhala.
Krátke zhrnutie
Administrátorská príručka ≠ používateľský manuál.
Používateľ rieši akciu.
Admin rieši systém.
Ak ich zmiešaš:
- vznikne chaos
- vzniknú falošné bugy
- vznikne závislosť na ľuďoch
Ak ich oddelíš:
- získaš kontrolu nad systémom
- zrýchliš onboarding
- znížiš riziko pri release
A to už nie je dokumentácia.
To je riadenie kvality produktu.