chyby

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

Najčastejšie chyby v technickej dokumentácii 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

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

 

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

Problém nie je, že dokumentácia chýba.…

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

Chybové stavy a funkčné obmedzenia systému

/

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

 

Reálny problém z praxe

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

  • aké kombinácie sú povolené
  • aké nie
  • čo je chyba a čo je zámer

Výsledok:

tester hlási bug
vývojár ho zamieta
support nevie, čo povedať zákazníkovi

 

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

Problém nie je v konkrétnom správaní.…

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

Administrátorská príručka, Dokumentácia a používateľské príručky

Najčastejšie chyby v administrátorských príručkách 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

Admin rieši incident v produkcii.

Nevie:

  • kde nájsť logy
  • aké zmeny boli nasadené
  • či je problém v konfigurácii alebo v kóde

Otvorí administrátorský manuál.

Nájde:

  • všeobecný popis systému
  • zoznam funkcií
  • pár screenshotov

Nenájde:

  • postup riešenia
  • hranice systému
  • reálne prevádzkové scenáre

Volá vývojára.…

Dokumentácia a používateľské príručky, Používateľské manuály

Najčastejšie chyby v používateľský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

Manuál existoval.

Bol „hotový“.
Bol odovzdaný.
Bol schválený.

A aj tak:

  • používatelia volali support
  • tester reportoval „bugy“
  • onboarding trval dlho

Keď som sa na to pozrela, nebol problém v tom, že by manuál chýbal.…

Návrat hore