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

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

Štruktúra release notes (čo má obsahovať jeden release)

/

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

Reálny problém z praxe

Firma vydá novú verziu systému.

Release notes vyzerajú takto:

  • oprava bugov
  • optimalizácia výkonu
  • drobné úpravy UI
  • vylepšenia systému

Používateľ nevie:

  • čo sa zmenilo
  • či sa ho to týka
  • či musí niečo robiť inak

Support nevie:

  • na čo sa pripraviť
  • ktoré incidenty môžu pribudnúť
  • ktoré staré workaroundy už neplatia

Tester nevie:

  • ktoré zmeny sa nakoniec dostali do release
  • čo bolo odložené
  • čo je breaking change

Release notes existujú.…

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

Odkiaľ release notes vznikajú (workflow: user story → task → bug → release)

/

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

Reálny problém z praxe

Vo firme sa blíži release.

Projektový manažér napíše:
„Pošlite mi zmeny do release notes.“

A začne chaos:

  • tester prehľadáva Jiru
  • vývojár si spomína, čo vlastne robil
  • support sa pýta, čo má komunikovať klientom
  • niekto kopíruje názvy taskov
  • niekto ručne píše zoznam bugov

Nakoniec vznikne dokument typu:

  • Oprava exportu
  • Zlepšenie výkonu
  • Úpravy workflow
  • Oprava validácie

Bez kontextu.…

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

Čo sú release notes a pre koho sú určené

/

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

Reálny problém z praxe

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

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

Praktická ukážka: ako čítať technickú dokumentáciu a overiť ju testovaním

/

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

 

Reálny problém z praxe

Tester dostane dokumentáciu k API:

„Endpoint vytvorí objednávku.“

V dokumentácii je:

  • URL
  • názov endpointu

Tester napíše test:

  • pošle request
  • dostane odpoveď
  • test prejde

O pár dní príde incident:

„Objednávky sa nevytvárajú správne.“…

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

Dokumentácia pre DevOps a infra tím

/

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

 

Reálny problém z praxe

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

  • čo má byť nastavené
  • kde
  • v akej hodnote

 

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

Problém nie je v deploymente.…

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

Core vs Custom v technickej dokumentácii

/

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

 

Reálny problém z praxe

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

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

Verziovanie technickej dokumentácie

/

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

 

Reálny problém z praxe

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

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

Monitoring, logovanie a observability

/

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

 

Reálny problém z praxe

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

  • čo sa loguje
  • kde sa to loguje
  • ako sa to dohľadá

Výsledok:

problém sa nedá overiť
a končí ako „nedá sa reprodukovať“

 

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

Problém nie je v chybe.…

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

Performance, limity a škálovanie

/

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

 

Reálny problém z praxe

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

  • čo je ešte v poriadku
  • čo už je problém
  • pri akom zaťažení sa to prejaví

Výsledok:

každý má inú predstavu o tom, čo znamená „pomalé“.…

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

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

Konfiguračné parametre a feature flags

/

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

 

Reálny problém z praxe

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

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

Návrat hore