Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Administrátorská príručka vznikala postupne.
Najprv core funkcionalita.
Potom klientská úprava.
Potom ďalší klient.
Po čase:
- konfigurácia je popísaná na viacerých miestach
- nie je jasné, čo je štandard a čo výnimka
- admin nevie, čo platí pre jeho prostredie
Typická otázka:
Platí toto pre všetkých, alebo len pre konkrétneho klienta?
Nikto si nie je istý.
Čo sa tu vlastne pokazilo (analýza systému)
Administrátorská príručka nemá vrstvy.
Core a Custom sú zmiešané v jednom texte.
Výsledok:
- nejasný rozsah platnosti
- konfliktné informácie
- dokumentácia sa nedá udržiavať
To nie je problém obsahu.
To je problém štruktúry.
Rovnaký problém sa objavuje aj pri používateľských manuáloch.
Skutočné náklady (čas, chaos, riziko)
- admin robí nesprávne konfigurácie
- support rieši „neexistujúce“ problémy
- tester nevie, čo je core scenár
- onboarding je pomalý
A hlavne:
Každá zmena znamená hľadanie, kde všade je to popísané.
Dokumentácia sa nedá škálovať.
Minimálny model riešenia
Administrátorská príručka musí byť rozdelená na dve vrstvy:
- Core (štandard produktu)
- Custom (klientské odchýlky)
Každá vrstva má inú logiku.
A inú štruktúru.
Šablóna č.1 – Core (hlavná vrstva)
Core sa píše tak, ako keby neexistovali klientské úpravy.
Názov oblasti
Konfigurácia autentifikácie
Popis
Definuje spôsob prihlasovania používateľov do systému.
Dostupné nastavenia
- typ autentifikácie (lokálna, LDAP, SSO)
- timeout relácie
- politika hesiel
Postup konfigurácie
- otvor administráciu
- nastav typ autentifikácie
- ulož zmeny
- reštartuj službu (ak je potrebné)
Dopady zmien
- zmena autentifikácie ovplyvní všetkých používateľov
- nesprávna konfigurácia môže zablokovať prístup
Obmedzenia
- SSO vyžaduje externý identitný provider
- LDAP musí byť dostupný zo siete
Šablóna č.2 – Custom (doplnková vrstva)
Custom sa píše ako odchýlka od Core.
Nikdy nie ako samostatný text.
Pre koho platí
Platí pre klienta XY
Čo je inak
Používa sa externý SSO provider s vlastnou konfiguráciou.
Rozdiel oproti Core
V štandardnom riešení sa používa lokálna autentifikácia alebo LDAP.
Dopad na admina
- konfigurácia sa nerobí len v aplikácii
- je potrebné nastavenie na strane klienta
Riziká
- nesprávne nastavenie SSO spôsobí nedostupnosť systému
- závislosť na externom systéme
Ako tieto vrstvy spolu fungujú
Core definuje:
- ako systém funguje
- čo je štandard
Custom dopĺňa:
- čo je inak
- pre koho to platí
Admin vždy číta:
- najprv Core
- potom svoju Custom vrstvu
Tak chápe:
- základ systému
- aj konkrétne odchýlky
Príklad (správne použitie)
Core:
Systém používa lokálnu autentifikáciu.
Custom:
Pre klienta XY sa používa SSO.
Výsledok:
Admin vie, čo je štandard a čo je výnimka.
Príklad (čo nefunguje)
Systém používa autentifikáciu, ktorá môže byť lokálna alebo externá podľa konfigurácie klienta.
Nejasné:
- čo je default
- čo je výnimka
- čo má admin reálne nastaviť
Mini checklist
- Je Core vrstva bez klientských výnimiek?
- Je Custom vždy označený „pre koho platí“?
- Je jasne popísaný rozdiel oproti Core?
- Vie admin, čo má reálne nastaviť?
- Dá sa dokumentácia rozširovať bez konfliktov?
Prepojenie na kvalitu a workflow
Táto štruktúra ovplyvňuje:
- testovanie (core vs custom scenáre)
- support (čo je štandard vs výnimka)
- onboarding (čo sa má nový človek naučiť)
Ak Core a Custom nie sú oddelené:
- testovanie sa mení na hádanie
- support robí nesprávne závery
- dokumentácia stráca dôveryhodnosť
Krátke zhrnutie
Univerzálna šablóna administrátorskej príručky nie je jeden text.
Je to model:
- Core vrstva definuje systém
- Custom vrstva vysvetľuje odchýlky
Ak sa to mieša, vzniká chaos.
Ak je to oddelené, dokumentácia sa dá udržiavať a škálovať.