Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Používateľ videl dáta, ktoré nemal vidieť.
Support to označil ako bug.
Vývoj odpovedal:
„To nie je bug, to je zlé nastavenie práv.“
Otvorili sme admin manuál.
Bola tam kapitola „Používatelia a roly“.
Popisovala, že existuje admin, manažér a používateľ.
Chýbalo:
- kto tieto roly nastavuje
- aké majú reálne oprávnenia
- aké sú výnimky
- aké sú dopady zmien
Výsledok:
Problém sa nedal vyriešiť bez telefonátu seniorovi.
Čo sa tu vlastne pokazilo (analýza systému)
Dokumentácia opisovala roly formálne, nie funkčne.
To znamená:
- názvy rolí existovali
- ale ich správanie nebolo definované
Chýbali tri kľúčové veci:
- Matrica oprávnení (kto má prístup k čomu)
- Dopady zmien (čo sa stane, keď zmením rolu alebo právo)
- Zodpovednosť (kto to nastavuje a kontroluje)
Bez toho dokumentácia neplní svoju úlohu.
Roly a bezpečnosť nie sú popis.
Sú to pravidlá systému.
Skutočné náklady (čas, chaos, riziko)
Ak nie sú roly a práva zdokumentované:
- vznikajú bezpečnostné incidenty
- support nevie rozlíšiť bug vs konfiguráciu
- tester testuje nesprávne scenáre
- onboarding nového admina je pomalý
- firma je závislá na konkrétnych ľuďoch
A typická veta z praxe:
„To sa takto používa, lebo to tak máme nastavené.“
Bez vysvetlenia prečo.
Minimálny model riešenia
Cieľ nie je popísať roly.
Cieľ je definovať správanie systému.
1. Matrica oprávnení
Každá rola musí mať jasne definované:
| Funkcionalita | Admin | Manažér | Používateľ |
| Vytvoriť záznam | áno | áno | áno |
| Schváliť záznam | áno | áno | nie |
| Vymazať záznam | áno | nie | nie |
Bez takejto tabuľky je dokumentácia nepresná.
2. Dopady zmien
Ku každej zmene musí byť uvedené:
- čo sa zmení
- koho sa to týka
- aké sú riziká
Príklad:
„Ak používateľ získa právo schvaľovať, môže uzatvárať proces bez kontroly manažéra.“
To je bezpečnostná informácia, nie technický detail.
3. Výnimky a špecifiká
Realita nikdy nie je čistá.
Dokumentácia musí obsahovať:
- výnimky pre konkrétne roly
- klientské úpravy
- dočasné riešenia
Inak vznikajú falošné očakávania.
4. Zodpovednosť
Každá operácia musí mať priradenú rolu:
- kto nastavuje práva
- kto ich schvaľuje
- kto ich kontroluje
Bez toho vznikajú konflikty medzi tímami.
5. Prepojenie na testovanie
Roly a práva nie sú len dokumentačná téma.
Tester musí vedieť:
- aké scenáre má testovať
- čo je očakávané správanie
- čo je porušenie bezpečnosti
Bez dokumentácie testovanie háda.
Mini checklist
- Existuje matica oprávnení?
- Sú definované dopady zmien?
- Sú uvedené výnimky a špecifiká?
- Je jasné, kto nastavuje a kontroluje práva?
- Vie tester podľa dokumentácie vytvoriť testy?
Ak nie, dokumentácia nepokrýva bezpečnosť.
Prepojenie na kvalitu a workflow
Roly a práva sú základ:
- bezpečnosti systému
- správneho fungovania procesov
- auditovateľnosti
Z testerského pohľadu:
Ak nie sú roly zdokumentované, nie je možné jednoznačne určiť, čo je chyba.
A to znamená:
- viac falošných bugov
- viac incidentov
- viac chaosu
Krátke zhrnutie
Dokumentovať roly neznamená pomenovať ich.
Znamená:
- definovať oprávnenia
- popísať dopady
- určiť zodpovednosť
Bez toho je administrátorská príručka neúplná.
A bezpečnosť systému je založená na domnienkach.