Séria: Ako písať dokumentáciu a manuály v IT projekte
Firma vydá novú verziu.
Na webe sa objaví krátky text:
„Zlepšili sme výkon a opravili chyby.“
Support však rieši desiatky otázok:
Séria: Ako písať dokumentáciu a manuály v IT projekte
Release je nasadený, úlohy sú zatvorené, bugy opravené. A potom príde otázka:
„Čo sa vlastne v tejto verzii zmenilo?“
Vývoj vie svoje. Tester si pamätá testované scenáre. Support zachytí prvé otázky používateľov. Obchodník povie klientovi niečo z hlavy.…
Príklad
Na portáli s článkami má redaktor možnosť vložiť do obsahu obrázky, videá z externých služieb (napr. YouTube) a podcasty ako audio prehrávače.
Používateľ si otvorí článok a očakáva, že:
V praxi sa však často stáva, že:
Tester teda netestuje len „či tam niečo je“, ale celý životný cyklus multimédia – od nahratia až po prehranie u používateľa.…
Príklad
Pracuješ na redakčnom systéme, kde sú minimálne tri roly: autor (redaktor), editor a admin.
Autor môže vytvoriť článok a uložiť ho ako draft. Editor ho môže upraviť a schváliť na publikovanie.
Problém nastane v praxi:
Zrazu nejde len o UI, ale o reálne porušenie procesu a bezpečnosti.…
Príklad
Redakčný systém umožňuje autorovi pripraviť článok dopredu a nastaviť publikovanie napr. na pondelok o 08:00. Redaktor článok schváli v piatok, nastaví dátum a čas publikovania a očakáva, že sa článok v pondelok ráno automaticky zobrazí na webe bez ďalšieho zásahu.
V praxi sa tu netestuje len „či sa to zobrazí“, ale celý mechanizmus: uloženie času, časové pásma, plánovač (CRON), cachovanie a aj správanie pri zmene alebo zlyhaní.…
Príklad
Predstav si portál pre online kurzy (LMS).
Študent si v ňom kúpi kurz a v rozvrhu vidí konkrétnu lekciu:
„Utorok 18:00 – Online hodina“.
Samotná hodina však neprebieha priamo v portáli, ale cez externý nástroj – napríklad Zoom, Microsoft Teams alebo Google Meet.
Používateľ klikne na tlačidlo „Pripojiť sa“ v portáli a očakáva, že sa dostane do správneho hovoru.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tester dostane dokumentáciu k API:
„Endpoint vytvorí objednávku.“
V dokumentácii je:
Tester napíše test:
O pár dní príde incident:
„Objednávky sa nevytvárajú správne.“…
Séria: Ako písať dokumentáciu a manuály v IT projekte
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ť.
Problém nie je, že dokumentácia chýba.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Release prebehol.
Aplikácia prestala fungovať.
Vývojár hovorí:
„Na dev to ide.“
DevOps odpovie:
„Na serveri je to nasadené správne.“
Tester vidí:
„Systém nefunguje.“
Nakoniec sa zistí:
chýbal konfiguračný parameter v produkcii.
Nikde nebolo napísané:
Problém nie je v deploymente.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tester hlási bug:
„Export nefunguje.“
Vývojár odpovie:
„U nás funguje.“
Support doplní:
„U iných zákazníkov to ide.“
Nakoniec sa zistí:
funkcionalita je upravená len pre konkrétneho klienta.
V dokumentácii je popísaný „štandardný systém“.…
Príklad
Používateľ dokončí kurz, systém zobrazí „Gratulujeme, získali ste certifikát“, ale PDF sa nedá stiahnuť.
Alebo ešte horšie – certifikát sa vygeneruje aj používateľovi, ktorý nesplnil všetky podmienky (napr. neprešiel testom alebo neprešiel všetkými lekciami).
V praxi to znamená stratu dôvery: certifikát má reprezentovať vedomosť alebo splnenie podmienok.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
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.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Support hlási:
„Používateľ tvrdí, že objednávka neprešla.“
Tester skúsi scenár.
Objednávka prejde.
Vývojár sa pýta:
„Máme k tomu logy?“
Nikto nevie.
V systéme nie je jasné:
Výsledok:
problém sa nedá overiť
a končí ako „nedá sa reprodukovať“
Problém nie je v chybe.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Používateľ hlási:
„Systém je pomalý.“
Tester to skúsi.
Raz je rýchly, raz pomalý.
Vývojár odpovie:
„U mňa to ide.“
Nikto nevie povedať:
Výsledok:
každý má inú predstavu o tom, čo znamená „pomalé“.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tester hlási:
„Systém nefunguje.“
Vývojár odpovie:
„To nie je chyba. To je obmedzenie.“
Používateľ zadal kombináciu údajov, ktorú systém nepodporuje.
Systém vrátil chybu.
Lenže nikde nebolo napísané:
Výsledok:
tester hlási bug
vývojár ho zamieta
support nevie, čo povedať zákazníkovi
Problém nie je v konkrétnom správaní.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tester hlási:
„Funkcia nefunguje.“
Vývojár odpovie:
„U mňa funguje.“
Support potvrdí:
„U zákazníka to nefunguje.“
Nakoniec sa zistí:
funkcia bola vypnutá konfiguračným parametrom.
Kód bol správny.
Test prešiel.
Len konfigurácia bola iná.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Používateľ hlási:
„Platba neprešla.“
V systéme objednávka existuje.
Platba nie.
Support rieši problém.
Tester skúša scenár znova.
Vývojár kontroluje kód.
Nakoniec sa zistí:
problém bol na strane externej platobnej brány.
Lenže v dokumentácii nebolo jasné:
Používateľ vidí jednu aplikáciu.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tester hlási:
„Používateľ vidí dáta, ktoré by nemal.“
Vývojár odpovie:
„Ale je prihlásený.“
Používateľ je prihlásený.
Ale nemá mať prístup k týmto dátam.
Nakoniec sa zistí:
Používateľ prešiel autentifikáciou.…
Príklad
Predstav si študenta, ktorý robí online skúšku. Má 30 minút na 20 otázok. Po odoslaní testu mu systém zobrazí iné skóre, než očakával. Neskôr sa ukáže, že niektoré otázky boli vyhodnotené nesprávne (napr. viac správnych odpovedí, ale systém počítal len jednu), a časový limit sa pri výpadku internetu nepozastavil.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tester hlási:
„API vracia chybu.“
Vývojár sa pýta:
„Aký endpoint? Aké parametre? Aký stavový kód?“
Tester nevie odpovedať.
V dokumentácii je len zoznam endpointov.
Bez parametrov. Bez príkladov. Bez chýb.
Výsledok:
API existuje.…
