Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Pri riešení incidentu sme otvorili administrátorský manuál.
Hľadali sme odpoveď na jednoduchú otázku: kto to má nastaviť.
Dokument opisoval konfiguráciu, ale nikde nebolo uvedené:
- kto za ňu zodpovedá
- kto ju môže meniť
- pre koho platí
Dodávateľ tvrdil, že to patrí klientovi.
IT admin klienta tvrdil, že to patrí dodávateľovi.
Biznis admin ani netušil, že taká konfigurácia existuje.
Nakoniec sa ukázalo, že problém nebol technický.
Bol dokumentačný.
Čo sa tu vlastne pokazilo (analýza systému)
V dokumentácii sa zmiešali dve veci, ktoré musia byť oddelené:
- Cieľové skupiny (kto dokumentáciu používa)
- Vrstvy dokumentácie (čo z reality systému vidí)
Cieľové skupiny (kto)
Administrátor nie je jedna rola. V praxi sú minimálne tri:
| Rola | Zodpovednosť |
| Dodávateľ | produkt, verzia, migrácie, bugy |
| IT admin (klient) | infraštruktúra, prevádzka, prístupy |
| Biznis admin (klient) | workflow, pravidlá, dáta |
Každá z týchto rolí robí iné rozhodnutia.
Preto potrebuje iný typ informácií.
Vrstvy dokumentácie (čo vidí)
Druhá os je rovnako dôležitá:
| Vrstva | Obsah |
| Interná dokumentácia dodávateľa | celý systém (core + všetky custom riešenia) |
| Klientská dokumentácia | len to, čo platí pre konkrétneho klienta |
Interná dokumentácia je kompletná mapa systému.
Klientská dokumentácia je filtrovaná realita.
Kde vzniká problém
Ak tieto dve osi nie sú prepojené:
- klient vidí funkcionality, ktoré nemá
- admin nevie, čo môže meniť
- support odpovedá podľa iného klienta
- tester testuje nesprávnu konfiguráciu
Skutočné náklady (čas, chaos, riziko)
Bez rozlíšenia cieľových skupín a vrstiev vznikajú:
- konflikty medzi dodávateľom a klientom
- nesprávne konfigurácie
- bezpečnostné chyby
- zbytočné incidenty
- falošné bugy
Typická veta z praxe:
„To sme mysleli, že robí druhá strana.“
Minimálny model riešenia
Stačí zaviesť jednoduché pravidlo:
Každá informácia v dokumentácii musí mať definované:
- komu je určená
- v akej vrstve platí
Prepojenie rolí a vrstiev
| Rola | Potrebuje | Má vidieť |
| Dodávateľ | celý systém | internú dokumentáciu (core + všetky custom riešenia) |
| IT admin | prevádzku a infra | klientskú administrátorskú dokumentáciu |
| Biznis admin | procesy a pravidlá | klientskú biznis dokumentáciu |
Príklad z praxe
Interná dokumentácia:
„Funkcia exportu podporuje viac formátov. Klient XY má custom validáciu dát.“
Klientská dokumentácia:
„Export dát obsahuje validáciu podľa vašich pravidiel. Pri chybe sa export nevykoná.“
Bez zmienky o iných klientoch.
Bez zbytočných detailov.
Praktické pravidlá
- Každá konfigurácia má priradenú rolu (kto ju nastavuje)
- Každá funkcionalita má označenie rozsahu (core alebo klientská úprava)
- Klientská dokumentácia neobsahuje informácie o iných klientoch
- Interná dokumentácia obsahuje kompletný obraz systému
Mini checklist
- Je v dokumentácii jasné, kto vykonáva danú operáciu?
- Je jasné, pre koho informácia platí?
- Sú oddelené interné a klientské informácie?
- Vie support podľa dokumentácie určiť zodpovednosť?
Ak nie, vznikajú procesné incidenty.
Prepojenie na kvalitu a workflow
Rozdelenie na roly a vrstvy nie je len dokumentačná technika.
Je to:
- základ zodpovednosti medzi dodávateľom a klientom
- základ bezpečnosti
- základ fungujúceho supportu
Z testerského pohľadu:
Ak tester nevie, ktorú vrstvu testuje, testuje nesprávnu realitu.
Krátke zhrnutie
Admin nie je jedna rola.
Dokumentácia nemá jednu vrstvu.
Roly určujú, kto robí rozhodnutia.
Vrstvy určujú, čo z reality vidí.
Ak tieto dve veci nespojíš:
- vzniká chaos
- vznikajú konflikty
- vznikajú falošné bugy
Ak ich prepojíš:
- dokumentácia začne riadiť zodpovednosť
- tím vie, kto má čo robiť
- systém je zrozumiteľný aj pre nových ľudí
Dokumentácia prestáva byť text.
Stáva sa mapou reality systému.