Ako a prečo písať rôzne druhy dokumentácie a príručiek (používateľská, správcovská, AI….)
Verzia 1.0 — účinná od: [dopíš dátum]
Táto smernica slúži na zjednotenie kritérií pripravenosti úloh pred začiatkom realizácie. Cieľom je minimalizovať nejasnosti, dodatočné otázky, nesprávne odhady a riziko implementácie na základe neúplných alebo nejasných požiadaviek.
Úloha sa nesmie zaradiť do vývoja, ak nespĺňa Definition of Ready (DoR).…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Nový tester dostane úlohu overiť funkcionalitu.
Otvorí dokumentáciu a nájde:
Séria: Ako písať dokumentáciu a manuály v IT projekte
Release vyšiel.
Release notes boli pripravené.
Používateľský manuál ostal starý.
Support manuál neobsahoval novú funkcionalitu.
Admin dokumentácia neobsahovala nové nastavenie.
A výsledok?
Séria: Ako písať dokumentáciu a manuály v IT projekte
Release vyšiel večer.
Ráno začali prichádzať incidenty.
Vývoj pritom tvrdil:
„Veď to bolo v release notes.“
A v release notes bola jedna veta:
Séria: Ako písať dokumentáciu a manuály v IT projekte
Používateľ otvorí release notes a prečíta si:
Lenže nikto nevie:
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.…
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.…
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“.…
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.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
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ť:
Výsledok:
každý má inú predstavu o tom, čo znamená „pomalé“.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
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é:
Výsledok:
tester hlási bug
vývojár ho zamieta
support nevie, čo povedať zákazníkovi
Problém nie je v konkrétnom správaní.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
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á.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
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é:
Používateľ vidí jednu aplikáciu.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
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í:
Používateľ prešiel autentifikáciou.…
