Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Tester hlási:
„Systém nefunguje podľa dokumentácie.“
Vývojár odpovie:
„Dokumentácia nie je aktuálna.“
Support dodá:
„Zákazník to robí inak.“
Každý má inú verziu pravdy.
Dokumentácia existuje.
Ale nedá sa podľa nej pracovať.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je, že dokumentácia chýba.
Problém je, že je nepoužiteľná.
Typické chyby sa opakujú naprieč projektmi.
Nie sú náhodné.
Sú systémové.
Skutočné náklady (čas, chaos, riziko)
Keď dokumentácia nefunguje:
- tester testuje nesprávne scenáre
- vývoj rieši nedorozumenia
- support dáva nepresné odpovede
- onboarding je pomalý
Najhorší stav:
dokumentácia existuje
ale tím ju ignoruje
Minimálny model riešenia
Nižšie sú najčastejšie chyby. Ku každej je praktická ukážka.
1. Dokumentácia nie je aktuálna
Chyba:
- API sa zmení
- dokumentácia ostane
Dopad:
- tester hlási bug, ktorý neexistuje
- integrácia zlyhá
Správne:
- dokumentácia je viazaná na verziu
- zmena = aktualizácia dokumentácie
2. Neexistuje rozlíšenie Core vs Custom
Chyba:
- popisuje sa „štandard“
- ignorujú sa klientské úpravy
Dopad:
- tester testuje nesprávne správanie
- support komunikuje nesprávne informácie
Správne:
- Core a Custom sú oddelené
- každá odchýlka je označená
3. Chýbajú chybové stavy a obmedzenia
Chyba:
- dokumentácia popisuje len „happy path“
Dopad:
- vznikajú falošné bugy
- tím si nerozumie
Správne:
- sú uvedené chybové scenáre
- je jasné, čo je obmedzenie
4. Chýba kontext systému
Chyba:
- nie je jasné, čo je náš systém
- nie je jasné, čo je externé
Dopad:
- problémy sa riešia na nesprávnom mieste
- support nevie eskalovať
Správne:
- systém má definované hranice
- externé závislosti sú popísané
5. Nezrozumiteľný dátový model
Chyba:
- názvy typu OMYL, C1, C2
- význam polí nie je popísaný
Dopad:
- tester nevie pracovať s dátami
- admin nevie opraviť chybu
Správne:
- polia majú význam
- je jasné, čo robia
6. Chýba dokumentácia konfigurácie
Chyba:
- feature flags existujú
- nikto nevie, čo robia
Dopad:
- systém sa správa inak v rôznych prostrediach
- vznikajú falošné bugy
Správne:
- konfigurácia je zdokumentovaná
- je jasný dopad zmien
7. API dokumentácia bez správania
Chyba:
- zoznam endpointov
- bez parametrov a chýb
Dopad:
- integrácie sa robia pokus-omyl
- tester nevie pripraviť testy
Správne:
- request, response, chyby
- jasné správanie
8. Chýba observability
Chyba:
- nie je jasné, čo sa loguje
- logy sa nedajú nájsť
Dopad:
- chyby sa nedajú analyzovať
- incidenty sa riešia naslepo
Správne:
- logovanie má kontext
- je jasné, kde ho nájsť
Mini checklist
Je dokumentácia aktuálna?
Je jasné, čo je Core a čo Custom?
Sú popísané chybové stavy?
Je definovaný kontext systému?
Je dátový model zrozumiteľný?
Je zdokumentovaná konfigurácia?
Je API použiteľné?
Je systém pozorovateľný?
Ak nie, dokumentácia neplní svoju funkciu.
Prepojenie na kvalitu a workflow
Technická dokumentácia nie je doplnok.
Je to kontrolný mechanizmus kvality.
Ak zlyhá:
- tím si nerozumie
- chyby sa opakujú
- systém je nepredvídateľný
Ak funguje:
- testovanie má oporu
- support má odpovede
- vývoj má stabilný základ
Krátke zhrnutie
Najväčší problém dokumentácie nie je, že neexistuje.
Problém je, že sa nedá použiť.
Najčastejšie chyby:
- neaktuálnosť
- nejasné hranice
- chýbajúce scenáre
- nezrozumiteľné dáta
Ak ich odstrániš:
dokumentácia začne fungovať
A tým sa zlepší celý projekt.