Ako a prečo písať rôzne druhy dokumentácie a príručiek (používateľská, správcovská, AI….)
Séria: Ako písať dokumentáciu a manuály v IT projekte
Support rieši problém:
„Export padá pri väčšom objeme dát.“
V Jire existuje bug:
Bug sa opraví.
Ticket sa uzavrie.
A tým to končí.
O pár dní príde rovnaký problém na support.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tím rieši incident:
Ticket sa uzavrie.
O pár dní príde rovnaký problém.
A nikto nevie, že už bol vyriešený.
Support dokumentácia existuje, ale:
Problém nie je v tom, že tím nevie písať dokumentáciu.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V produkcii vznikne incident:
„Používateľom sa nevytvárajú faktúry.“
Support to rieši:
Problém sa vyrieši.
O týždeň príde rovnaký incident.
A rieši sa znova.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Support dostane otázku:
„Prečo sa mi nevytvorila faktúra?“
Otvorí dokumentáciu a nájde:
„Modul Fakturácia umožňuje vytvárať, upravovať a exportovať faktúry…“
To je síce pravda.
Ale nepomáha to vyriešiť problém.
Support nevie:
A ide sa pýtať seniora.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Support dostane ticket:
„Používateľ sa nevie prihlásiť.“
Začne sa klasické kolečko:
Každý rieši rovnaké otázky stále dokola.
A dokumentácia?
Buď neexistuje, alebo obsahuje kapitolu:
„Prihlásenie do systému umožňuje…“
To supportu nepomôže.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Používateľ napíše na support:
„Nejde mi export faktúry.“
Support otvorí dokumentáciu. Nájde kapitolu:
„Export faktúr umožňuje exportovať dáta do XML formátu…“
Žiadna zmienka o chybe.
Žiadny postup, čo skontrolovať.
Žiadne príklady chýb.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Funkcionalita je implementovaná.
Existuje:
Ale administrátorská príručka chýba alebo je neúplná.
Admin potom:
Výsledok:
Funkcionalita existuje.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Administrátorská príručka vznikala postupne.
Najprv core funkcionalita.
Potom klientská úprava.
Potom ďalší klient.
Po čase:
Typická otázka:
Platí toto pre všetkých, alebo len pre konkrétneho klienta?…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Admin rieši incident v produkcii.
Nevie:
Otvorí administrátorský manuál.
Nájde:
Nenájde:
Volá vývojára.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Na projekte sa pripraví špecifikácia.
Obsahuje:
Vývoj začne implementovať.
Po čase sa objavia otázky:
Séria: Ako písať dokumentáciu a manuály v IT projekte
Systém bol nedostupný.
Používatelia hlásili výpadok.
Klient očakával okamžitú opravu.
Dodávateľ tvrdil, že problém je v infraštruktúre klienta.
IT admin klienta tvrdil, že aplikácia nefunguje.
Support nevedel, komu incident priradiť.
Výsledok:
Problém nebol len technický.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Nasadili sme novú verziu.
Niečo prestalo fungovať.
Nikto presne nevedel:
Rollback nebol pripravený.
A systém sa nedal rýchlo stabilizovať.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Používateľ nahlásil, že sa nedá prihlásiť.
Support to posunul ako bug.
Tester to nevedel reprodukovať.
Vývoj nenašiel chybu.
Nakoniec sa ukázalo, že problém bol v expirovanom tokene.
Stačilo pozrieť log.
Lenže nikto nevedel:
A tak sa riešil incident bez dát.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Raz som riešila bug, ktorý na prvý pohľad vyzeral ako chyba aplikácie.
Správanie systému bolo nesprávne, ale nebolo jasné prečo.
Postupne som začala kontrolovať staršie verzie, krok po kroku späť, až som našla bod zlomu: pri jednej verzii to ešte fungovalo, pri novšej už nie.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Funkcionalita prestala fungovať.
Používateľ ju nevidel.
Support to označil ako bug.
Tester to nevedel reprodukovať.
Nakoniec sa ukázalo, že bola vypnutá konfigurácia.
V dokumentácii bola uvedená.
Len ako názov parametra.
Bez vysvetlenia:
Výsledok:
Tri tímy riešili „bug“, ktorý bol nastavenie.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Používateľ videl dáta, ktoré nemal vidieť.
Support to označil ako bug.
Vývoj odpovedal:
„To nie je bug, to je zlé nastavenie práv.“
Otvorili sme admin manuál.
Bola tam kapitola „Používatelia a roly“.
Popisovala, že existuje admin, manažér a používateľ.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Nový admin dostal „admin manuál“.
Mal podľa neho nastaviť systém.
Po chvíli sa začal pýtať:
Séria: Ako písať dokumentáciu a manuály v IT projekte
Pri riešení incidentu sme otvorili administrátorský manuál.
Hľadali sme odpoveď na jednoduchú otázku: kto to má nastaviť.
Dokument opisoval konfiguráciu, ale nikde nebolo uvedené:
Dodávateľ tvrdil, že to patrí klientovi.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
V projekte sme mali „manuál“.
Volal sa rovnako pre všetkých – manuál.
Používateľ v ňom hľadal, čo má kliknúť.
Admin v ňom hľadal, ako nastaviť systém.
Support v ňom hľadal, prečo to nefunguje.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Názov: Export faktúr do XML
User story:
Ako účtovník
chcem exportovať faktúry do XML
aby som ich mohol importovať do účtovného systému
Popis funkcionality:
Systém umožňuje exportovať faktúry do XML súboru na základe zvoleného rozsahu dátumov.…
