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