Pridanie komentárov pod články, videá alebo lekcie vyzerá na prvý pohľad jednoducho. V praxi je to však kombinácia formulárov, práv používateľov, notifikácií, moderovania, bezpečnosti a výkonu.
Predstav si portál s online kurzami. Používateľ pridá komentár pod lekciu:
„Video sa mi nedá prehrať od 15:30.“
Lektor dostane notifikáciu, odpovie na komentár a administrátor neskôr nevhodný komentár zmaže.…
Príklad
Predstav si spravodajský portál alebo LMS systém, kde sa články, obrázky, videá a štýly načítavajú cez CDN sieť. Redaktor upraví titulný obrázok článku alebo opraví chybu v texte, ale časť používateľov stále vidí starú verziu obsahu. Iní používatelia už vidia novú verziu. Ďalší majú rozbitý layout, pretože sa načítal nový CSS súbor, ale starý JavaScript zostal v cache.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Firma vydá novú verziu systému.
Release notes vyzerajú takto:
Používateľ nevie:
Support nevie:
Tester nevie:
Release notes existujú.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Vo firme sa blíži release.
Projektový manažér napíše:
„Pošlite mi zmeny do release notes.“
A začne chaos:
Nakoniec vznikne dokument typu:
Bez kontextu.…
Príklad
Predstavme si vzdelávací portál, ktorý má na začiatku iba niekoľko kurzov, desiatky lekcií a pár stoviek používateľov.
Po čase sa však obsah rozrastie:
Príklad
Predstav si portál s článkami (napr. blog, spravodaj alebo LMS). Redaktor vytvorí článok „Ako testovať API“.
Vyplní:
Na prvý pohľad všetko vyzerá správne.…
Príklad
Predstav si portál (napr. spravodajský web alebo LMS), ktorý:
Používateľ vidí obsah „ako keby bol náš“, ale v skutočnosti:
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.…
