apríl 2026

Ako písať technickú dokumentáciu, Dokumentácia a používateľské príručky

Integrácie a externé závislosti

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

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é:

  • že ide o externú službu
  • kde končí zodpovednosť systému
  • čo sa má stať pri chybe

Používateľ vidí jednu aplikáciu.…

Ako písať technickú dokumentáciu, Dokumentácia a používateľské príručky

Autentifikácia, autorizácia a bezpečnosť

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

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í:

  • role sú nastavené nesprávne
  • kontrola oprávnení sa robí len na frontende
  • API neoveruje prístup

Používateľ prešiel autentifikáciou.…

Ako testovať..., Konkrétne oblasti, LMS (Learning Management System)

Ako testovať testy a skúšky (časové limity, typy otázok, výsledky)

/

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.…

Ako písať technickú dokumentáciu, Dokumentácia a používateľské príručky

Ako zapisovať architektúru systému, aby sa podľa nej dalo pracovať

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

Reálny problém z praxe

V projekte „architektúra existovala“.

Bol tam obrázok.

Krásny diagram.
Krabice, šípky, názvy služieb.

Keď prišiel problém, všetci ho otvorili.

A potom nasledovala otázka:

„A čo to vlastne znamená?“

Diagram ukazoval prepojenia.
Ale neukazoval správanie.…

Ako písať technickú dokumentáciu, Dokumentácia a používateľské príručky

Architektúra systému – komponenty a komunikácia

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

Tester hlási:

„Uloženie objednávky trvá 10 sekúnd.“

Vývojár otvorí backend.
Databáza je rýchla.
API odpovedá.

Nakoniec sa zistí, že problém je v komunikácii medzi službami.

Lenže nikto presne nevedel:

koľko komponentov sa do toho zapája
v akom poradí sa volajú
kde sa môže spomaliť systém

Všetko bolo „nejako prepojené“.…

Ako písať technickú dokumentáciu, Dokumentácia a používateľské príručky

Kontext systému – čo je systém a čo nie

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

Tester hlási bug:

„Systém neposlal notifikáciu.“

Vývojár odpovie:

„To nie je náš systém. To robí externá služba.“

Support povie:

„Ale používateľ to vidí ako jednu aplikáciu.“

A zákazník má jasno:

„Nezaujíma ma, kto za to môže.…

Ako testovať..., Konkrétne oblasti, LMS (Learning Management System)

Ako testovať kurzy a moduly (dostupnosť, poradie lekcií)

/

Príklad

Predstav si študenta, ktorý si kúpi online kurz. Po prihlásení vidí prvú lekciu, ale ďalšie sú zamknuté, aj keď splnil podmienky. Inde sa mu lekcie zobrazujú v nesprávnom poradí – najskôr test, potom teória.
Výsledok: frustrácia, znížená dôvera a reklamácie.

Pri LMS systémoch je kritické, aby bol obsah dostupný správnym používateľom, v správnom čase a v logickom poradí.…

Dokumentácia a používateľské príručky, Manuály pre technickú podporu

Praktické ukážky: 3–5 reálnych support scenárov (z user story + akceptačné kritériá + špecifikácia + bugy → hotové support položky)

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

Tím má:

  • user story
  • akceptačné kritériá
  • špecifikáciu
  • bugy

Support má:

  • otázky od používateľov

Medzi tým nie je prepojenie.

Výsledok:

  • support nevie, čo systém robí
  • nevie, čo je chyba
  • nevie, čo je očakávané správanie

Dokumentácia existuje, ale nie je napojená na realitu.…

Dokumentácia a používateľské príručky, Manuály pre technickú podporu

Najčastejšie chyby v interných manuáloch a ich dopad na projekt (praktické ukážky)

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

Firma má interné manuály.

Support ich otvorí.

Ale:

  • nenájde odpoveď
  • alebo nájde niečo neaktuálne
  • alebo nevie, či je to správne

A ide sa pýtať kolegu.

Dokumentácia existuje.
Ale nepoužíva sa.

 

Čo sa tu vlastne pokazilo (analýza systému)

Chyba nie je jedna.…

Dokumentácia a používateľské príručky, Manuály pre technickú podporu

Ako merať efektivitu support dokumentácie

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

Firma má support dokumentáciu.

Má desiatky článkov.
Možno stovky.

Nikto však nevie:

  • či sa používa
  • či pomáha
  • či má zmysel

Dokumentácia existuje.

Ale jej hodnota je len pocit.

 

Čo sa tu vlastne pokazilo (analýza systému)

Dokumentácia sa nemeria.…

Dokumentácia a používateľské príručky, Manuály pre technickú podporu

Ako udržiavať support dokumentáciu aktuálnu (verzie, zastarané riešenia, archivácia)

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

Support otvorí dokumentáciu.

Nájde riešenie.

Postupuje podľa neho.

Nefunguje.

Po chvíli zisťuje:

  • postup je zastaraný
  • systém sa medzitým zmenil
  • workaround už neplatí

A ide sa pýtať kolegu.

 

Čo sa tu vlastne pokazilo (analýza systému)

Dokumentácia existuje.…

Dokumentácia a používateľské príručky, Manuály pre technickú podporu

Univerzálna šablóna support položky (ready-to-use pre prax)

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

Support dokumentácia existuje.

Každý ju píše po svojom:

  • niekto opisuje funkcionalitu
  • niekto píše voľný text
  • niekto dá len pár bodov

Výsledok:

  • nedá sa v tom vyhľadávať
  • nedá sa to použiť konzistentne
  • každá odpoveď vyzerá inak

A hlavne:

rovnaké problémy sa riešia rôznymi spôsobmi.…

Dokumentácia a používateľské príručky, Manuály pre technickú podporu

Ako štruktúrovať support znalostnú bázu (tagy, názvy, vyhľadateľnosť)

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

Support má dokumentáciu.

Obsahuje desiatky, neskôr stovky položiek:

  • incidenty
  • bugy
  • riešenia

Keď príde problém:

„Používateľ sa nevie prihlásiť“

Support začne hľadať.

Výsledok:

  • nenájde nič
  • alebo nájde 10 podobných článkov
  • alebo nájde nesúvisiaci výsledok

A ide sa pýtať kolegu.…

Dokumentácia a používateľské príručky, Manuály pre technickú podporu

Workaroundy a dočasné riešenia – ako ich zapisovať, aby nepoškodili produkt

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

 

Reálny problém z praxe

V produkcii vznikne problém:

„Export padá pri veľkom objeme dát.“

Riešenie zatiaľ neexistuje.
Vývoj pripraví workaround:

  • rozdeliť export na menšie časti

Support to začne používať.
Klientom to funguje.

O pár mesiacov:

  • workaround sa používa ako štandard
  • nikto nevie, že ide o dočasné riešenie
  • bug sa už nerieši

 

Čo sa tu vlastne pokazilo (analýza systému)

Workaround vznikol správne.…

Dokumentácia a používateľské príručky, Manuály pre technickú podporu

Core vs Custom v support dokumentácii

/

Séria: Ako písať dokumentáciu a manuály v IT projekte

Reálny problém z praxe

Support dostane otázku:

„Prečo u nás funguje export inak ako u iného klienta?“

Support nevie odpovedať.

Začne zisťovať:

  • je to bug?
  • je to konfigurácia?
  • je to nová funkcionalita?

Nakoniec sa ukáže:

  • ide o klientskú úpravu

Ale táto informácia:

  • nie je v dokumentácii
  • nie je označená
  • existuje len „v hlave“

Čo sa tu vlastne pokazilo (analýza systému)

Dokumentácia nerozlišuje:

  • čo je Core (štandard produktu)
  • čo je Custom (klientská úprava)

Všetko je zmiešané.…

Návrat hore