Ako písať príručku pre administrátorov systému
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
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.…
