Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Nový admin dostal „admin manuál“.
Mal podľa neho nastaviť systém.
Po chvíli sa začal pýtať:
- Toto mám robiť ja alebo dodávateľ?
- Toto je technická konfigurácia alebo biznis nastavenie?
- Prečo je tu polovica vecí, ktoré sa nás netýkajú?
Dokument existoval.
Použiť sa nedal.
Čo sa tu vlastne pokazilo (analýza systému)
Administrátorská príručka bola napísaná ako jeden lineárny dokument.
Bez rozlíšenia:
- rôznych typov adminov
- rôznych úrovní zodpovednosti
- rôznych vrstiev systému
Výsledok:
- každý v nej hľadá niečo iné
- nikto si nie je istý, čo je jeho zodpovednosť
Z predchádzajúcich tém platí:
Admin nie je jedna rola.
Máme minimálne:
- dodávateľa
- IT admina
- biznis admina
Ak štruktúra dokumentu nerešpektuje tieto roly, dokumentácia zlyháva.
Skutočné náklady (čas, chaos, riziko)
Zle štruktúrovaná admin príručka spôsobuje:
- nesprávne konfigurácie
- zásahy mimo kompetencií
- zbytočné eskalácie
- závislosť na senioroch
- chyby pri upgrade a incidente
A typická realita:
dokumentácia existuje, ale tím ju nepoužíva
Minimálny model riešenia
Cieľ nie je mať viac textu.
Cieľ je mať správnu štruktúru.
Základný princíp
Každá kapitola musí jasne odpovedať:
- kto ju používa
- čo rieši
- v akej vrstve systému sa pohybuje
Odporúčaná štruktúra administrátorskej príručky
1. Úvod a rozsah
- pre koho je dokument určený (dodávateľ / IT / biznis admin)
- čo dokument pokrýva a čo nie
- základné pojmy
Cieľ: nastaviť očakávania.
2. Roly a zodpovednosti
- rozdelenie admin rolí
- kto za čo zodpovedá
- kto má aké oprávnenia
Príklad:
| Aktivita | Rola |
| Nasadenie verzie | dodávateľ |
| Správa servera | IT admin |
| Nastavenie workflow | biznis admin |
Táto kapitola je kritická.
Bez nej je všetko ostatné nejasné.
3. Architektúra systému (primeraná úroveň)
- základné komponenty
- externé závislosti
- tok dát
Nie detail pre vývojára, ale kontext pre admina.
4. Systémové požiadavky
- minimálne a odporúčané HW
- softvérové závislosti
- kompatibilita
Admin potrebuje vedieť, kde sú limity systému.
5. Inštalácia a nasadenie
- prvotná inštalácia
- inicializácia systému
- overenie funkčnosti
Musí byť možné postup vykonať bez otázok.
6. Konfigurácia systému
Tu je potrebné rozdelenie:
6.1 Technická konfigurácia (IT admin)
- databáza
- certifikáty
- sieť
- integrácie
6.2 Biznis konfigurácia (biznis admin)
- workflow
- pravidlá
- číselníky
- používateľské oprávnenia
Ku každej konfigurácii:
- čo robí
- aký má dopad
- čo sa stane pri zlej hodnote
7. Integrácie a externé služby
- prehľad integrácií
- autentifikácia
- závislosti
- zodpovednosť (kto spravuje čo)
8. Logovanie a diagnostika
- kde nájsť logy
- čo znamenajú chyby
- ako postupovať pri probléme
Prepojenie na support dokumentáciu.
9. Incidenty a riešenie problémov
- typické scenáre
- základná diagnostika
- kedy eskalovať
Nie „kontaktujte podporu“, ale postup.
10. Upgrade a rollback
- príprava na upgrade
- samotný postup
- kontrola po upgrade
- rollback scenár
Bez tejto kapitoly admin príručka nie je kompletná.
11. Obmedzenia systému (known limitations)
- čo systém nepodporuje
- hraničné prípady
- výkonnostné limity
Znižuje falošné bugy.
12. Core vs Custom (ak je relevantné)
- čo je súčasť produktu
- čo je klientská úprava
- rozsah platnosti funkcionalít
Mini checklist
- Je jasné, kto má ktorú kapitolu používať?
- Sú oddelené technické a biznis nastavenia?
- Sú uvedené dopady konfigurácie?
- Dá sa podľa dokumentácie spraviť upgrade?
- Sú definované obmedzenia systému?
Prepojenie na kvalitu a workflow
Štruktúra admin príručky priamo ovplyvňuje:
- kvalitu konfigurácie
- bezpečnosť systému
- rýchlosť riešenia incidentov
- onboarding nových ľudí
Z testerského pohľadu:
- ak nie je jasná štruktúra, tester nevie, čo je chyba a čo konfigurácia
Krátke zhrnutie
Administrátorská príručka nie je jeden dokument pre všetkých.
Musí rešpektovať:
- rôzne typy adminov
- rôzne zodpovednosti
- rôzne vrstvy systému
Ak je dobre štruktúrovaná:
- každý nájde to, čo potrebuje
- tím vie, kto za čo zodpovedá
- systém je riaditeľný bez závislosti na jednom človeku
To je rozdiel medzi dokumentáciou, ktorá existuje,
a dokumentáciou, ktorá sa používa.