Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Tester hlási bug:
„API nefunguje podľa dokumentácie.“
Vývojár odpovie:
„To už neplatí. To bolo v starej verzii.“
Tester má otvorený dokument.
Vývojár má v hlave aktuálny stav.
Obaja majú pravdu.
Len každý pracuje s inou verziou reality.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nie je v chybe.
Problém je, že dokumentácia nemá verziu.
Systém sa mení:
- API sa upraví
- pole sa premenuje
- parameter sa zruší
- správanie sa zmení
Dokumentácia ostane rovnaká.
Alebo:
existuje viac verzií
a nikto nevie, ktorá platí
Skutočné náklady (čas, chaos, riziko)
Keď dokumentácia nemá verzie:
- tester testuje podľa neplatných informácií
- integrácie sa rozbijú
- support dáva nesprávne odpovede
- onboarding je pomalý
Typická situácia:
problém nie je v systéme
problém je v nesúlade medzi dokumentáciou a realitou
Minimálny model riešenia
Netreba komplikovaný systém.
Treba jasné pravidlá.
1. Prepojenie na release
Každá dokumentácia musí byť viazaná na verziu systému:
- verzia aplikácie
- verzia API
- release
Bez toho nevieš, čo platí.
2. Označenie zmien
Pri každej zmene musí byť jasné:
- čo sa zmenilo
- kedy sa to zmenilo
- od ktorej verzie to platí
3. História
Dokumentácia nemá byť prepísaná.
Má byť verzovaná.
To znamená:
- staré verzie zostávajú
- nové verzie pribúdajú
4. Breaking changes
Najkritickejšia časť:
- čo prestalo fungovať
- čo sa zmenilo nekompatibilne
- čo musí klient upraviť
5. Jednoznačný zdroj pravdy
Musí existovať:
- jedno miesto, kde je aktuálna dokumentácia
- bez duplikátov
- bez nejasností
Príklad
Bez verziovania:
„Endpoint vracia pole STATUS.“
S verziovaním:
- verzia 1.0 → pole STATUS
- verzia 2.0 → pole STATE
- od verzie 2.0 je STATUS zrušené
Zrazu je jasné:
čo je správne
čo testovať
čo upraviť
Mini checklist
Je dokumentácia viazaná na verziu?
Je jasné, čo sa zmenilo?
Existuje história zmien?
Sú označené breaking changes?
Existuje jeden zdroj pravdy?
Ak nie, dokumentácia nie je spoľahlivá.
Prepojenie na kvalitu a workflow
Verziovanie dokumentácie je základ pre:
- testovanie
- integrácie
- release
- support
Bez neho:
- tester nevie, čo má platiť
- vývojár vysvetľuje zmeny ústne
- systém je nepredvídateľný
Pre testerku je to kritické:
Testuješ vždy konkrétnu verziu.
Nie „nejaký systém“.
Krátke zhrnutie
Systém sa mení.
Dokumentácia musí tiež.
Ak nie je verzovaná:
- vzniká chaos
- tím si nerozumie
Ak je:
- vieš, čo platí
- vieš, čo sa zmenilo
- vieš, čo testovať
A to je základ riadeného vývoja.