Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
V projekte bol „manuál“.
Používateľ v ňom hľadal, čo má kliknúť.
Tester v ňom hľadal, ako sa to má správať.
Vývojár v ňom hľadal, ako to funguje.
Nikto nenašiel to, čo potreboval.
A keď prišla otázka:
„Prečo to nefunguje?“
Odpoveď bola mimo dokumentácie – v hlave konkrétneho človeka.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je, že dokumentácia neexistuje.
Problém je, že sa miešajú rôzne typy dokumentácie.
Zmiešali sa dva svety:
Typ dokumentácie
- Používateľský manuál
- Technická dokumentácia
Otázka, ktorú riešia
- „Čo mám urobiť?“
- „Ako systém funguje?“
Pre koho
- koncový používateľ
- vývojár, integrátor, DevOps, tester
Používateľský manuál:
- scenáre („ako vytvoriť…“)
- jednoduchý jazyk
- minimum technických detailov
Technická dokumentácia:
- architektúra systému
- dátový model
- API
- integrácie
- závislosti
- obmedzenia
Ak to spojíš, stratí sa účel.
Skutočné náklady (čas, chaos, riziko)
Keď technická dokumentácia neexistuje (alebo je zamaskovaná ako user manuál):
- vývojár sa pýta „ako to vlastne funguje“
- tester testuje len UI, nie systém
- integrácie sa robia pokus-omyl
- onboarding stojí na senioroch
- vznikajú falošné bugy
Najčastejšie:
- problém nie je v kóde
- problém je v tom, že nikto nevie, čo systém robí
Minimálny model riešenia
Netreba veľa. Treba oddeliť veci.
Základný model:
- Používateľský manuál
- scenáre
- kroky
- bez technických detailov
- Technická dokumentácia
Musí obsahovať minimálne:
- Kontext systému (čo je systém a čo nie)
- Architektúru a komponenty
- Tok dát
- API a integrácie
- Konfiguráciu a feature flags
- Chybové stavy a obmedzenia
- Verziovanie
- Support dokumentácia (oddelene)
- symptóm → príčina → riešenie
Príklad rozdielu (jedna funkcionalita)
User manuál:
Kliknite na „Odoslať objednávku“.
Technická dokumentácia:
Po odoslaní sa volá endpoint /orders.
Pri chybe vracia kód 409 (duplicitná objednávka).
Ak je zapnutý feature flag ORDER_VALIDATION, vykoná sa dodatočná validácia.
To je rozdiel.
Mini checklist (rýchla kontrola)
Ak si chceš overiť, či máš technickú dokumentáciu:
- Je jasné, pre koho je určená?
- Obsahuje architektúru a dáta?
- Sú popísané integrácie a závislosti?
- Sú uvedené chybové stavy a obmedzenia?
- Dá sa podľa nej pochopiť správanie systému bez otázok?
Ak nie → nie je to technická dokumentácia.
Prepojenie na kvalitu a workflow
Technická dokumentácia nie je doplnok.
Bez nej:
- testovanie nevidí systém
- support nevie diagnostikovať problém
- integrácie zlyhávajú
- onboarding je pomalý
A hlavne:
- tím nerozumie vlastnému produktu
Technická dokumentácia je miesto, kde sa ukáže, či firma chápe svoj systém.
Krátke zhrnutie
Technická dokumentácia ≠ používateľský manuál.
Používateľ rieši akciu.
Technická dokumentácia rieši systém.
Ak ich zmiešaš:
- stratí sa zmysel
- vznikne chaos
- vznikne závislosť na ľuďoch
Ak ich oddelíš:
- získaš kontrolu nad systémom
- zrýchliš onboarding
- zlepšíš testovanie
A to už nie je dokumentácia.
To je riadenie kvality produktu.