Dokumentácia a používateľské príručky

Ako a prečo písať rôzne druhy dokumentácie a príručiek (používateľská, správcovská, AI….)

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

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