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