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ť:
Príklad
Na prvý pohľad vyzerá vyhľadávanie v obsahovom systéme jednoducho. Používateľ zadá slovo, systém niečo nájde a zobrazí výsledky. V praxi sa však práve tu často láme dôvera v celý produkt.
Predstav si redakčný portál alebo firemný knowledge base systém. Autor pridá článok s názvom „Zmena fakturačných údajov“, označí ho tagmi fakturácia, profil, zákazník a zaradí do kategórie Pomoc.…
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.…
Príklad
Predstav si redakčný systém, v ktorom editor upraví už publikovaný článok. Pri úprave omylom prepíše dôležitý odsek, zmení titulok a odstráni interný odkaz. Na prvý pohľad je všetko uložené správne, ale po zverejnení si tím všimne, že článok má horší význam, chýbajú v ňom dôležité informácie a prepadla sa aj návštevnosť z vyhľadávania.…
Príklad
Predstav si redakčný systém, kde autor napíše článok a odošle ho na schválenie. Editor ho upraví a nastaví publikovanie.
Na prvý pohľad všetko funguje.
Lenže:
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.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Manuál existoval.
Bol „hotový“.
Bol odovzdaný.
Bol schválený.
A aj tak:
Keď som sa na to pozrela, nebol problém v tom, že by manuál chýbal.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Manuál bol jeden.
Používali ho:
Výsledok:
Obaja mali pravdu.
Manuál nebol zlý.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Manuál bol plný obrázkov.
Každý krok mal screenshot.
Šípky, krúžky, zvýraznenia.
Používateľ aj tak volal support:
„Ja to tam nemám.“
Ukázalo sa:
Používateľ nehľadal funkciu.…
Príklad
Predstav si redaktora, ktorý pripraví článok, uloží ho ako draft a plánuje publikovanie na ráno.
Ráno sa článok zobrazí na webe — ale bez obrázkov, so starou verziou textu a bez SEO titulku.
Výsledok:
CMS nie je len „editor textu“.…
Príklad
Používateľ si predplatí film v online platforme. Film sa prehrá bez problémov, ale zároveň si otvorí vývojársku konzolu v prehliadači a skúsi nájsť URL na video súbor.
Ak sa mu podarí súbor stiahnuť priamo, systém síce funguje pre bežného používateľa, ale z pohľadu bezpečnosti zlyhal.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Tím napíše manuál.
Pri prvej zmene funkcionality ho upraví.
Pri druhom klientovi ho rozšíri.
Pri treťom klientovi doplní výnimky.
Po čase:
A keď príde nový kolega:
„Platí toto pre všetkých?“…
Príklad
Používateľ si stiahne film v mobilnej aplikácii počas Wi-Fi pripojenia, aby si ho pozrel neskôr offline. Počas cesty bez internetu film prehrá bez problémov.
Po opätovnom pripojení sa však zistí, že systém nezaznamenal prehranie, nesprávne vyhodnotil licenciu a používateľovi zablokoval ďalší obsah.
Offline režim nie je len „funguje / nefunguje“ – je to kombinácia lokálnych dát, cache, práv a následnej synchronizácie.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Používateľ si otvorí manuál.
Nájde funkcionalitu, ktorú v systéme nemá.
Volá support:
„Prečo to u mňa nefunguje?“
Support zisťuje:
„To máme len u klienta XY.“
Tester si myslí, že je to bug.
Vývojár tvrdí, že je to custom.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Manuál existoval.
Bol „dobre napísaný“.
A aj tak:
Keď som sa na to pozrela bližšie, problém nebol v tom, že by tam informácie neboli.…
Séria: Ako písať dokumentáciu a manuály v IT projekte
Vyšla nová verzia systému.
Funkcionalita sa nezmenila zásadne.
Len:
Manuál bol zrazu nepoužiteľný.
Používateľ postupoval podľa neho a zasekol sa na kroku:
„Kliknite na tlačidlo Export vpravo hore.“…
