Ako písať technickú dokumentáciu
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.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tester hlási:
„API vracia chybu.“
Vývojár sa pýta:
„Aký endpoint? Aké parametre? Aký stavový kód?“
Tester nevie odpovedať.
V dokumentácii je len zoznam endpointov.
Bez parametrov. Bez príkladov. Bez chýb.
Výsledok:
API existuje.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Admin klienta napísal:
„Pracovníčka omylom zmazala záznam. Dá sa obnoviť?“
Na prvý pohľad jednoduchá otázka.
V testovacom prostredí som zmazala záznam.
V databáze som ho našla.
Lenže:
nevedela som, ako ho obnoviť.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tester hlási:
„Objednávka sa uložila, ale neobjavila sa vo výpise.“
Vývojár skontroluje databázu.
Dáta tam sú.
Frontend ich neukazuje.
API ich vracia.
Nakoniec sa zistí, že objednávka má stav, ktorý frontend neberie do úvahy.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
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.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
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é“.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
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.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V projekte bol „manuál“.
Používateľ v ňom hľadal, čo má kliknúť.
Tester v ňom hľadal, ako sa to má správať.
Vývojár v ňom hľadal, ako to funguje.
Nikto nenašiel to, čo potreboval.…
