Univerzálna šablóna používateľského manuálu (core + custom vrstva)

Séria: Ako písať dokumentáciu a manuály v IT projekte

Reálny problém z praxe

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:

rovnaká funkcionalita je opísaná na troch miestach
text si protirečí
nikto nevie, čo je vlastne štandard

A keď príde nový kolega:

„Platí toto pre všetkých?“

Nikto si nie je istý.

Čo sa tu vlastne pokazilo (analýza systému)

Manuál nemá štruktúru.

Presnejšie:

nemá oddelené vrstvy.

Core a Custom sa píšu naraz, v jednom texte.

Výsledok:

miešanie informácií
nejasný rozsah platnosti
dokumentácia sa nedá udržiavať

To nie je problém písania.

To je problém modelu.

Skutočné náklady (čas, chaos, riziko)

každá zmena = hľadanie, kde všade to je
support nevie, čo platí pre koho
tester nevie, čo je core scenár
onboarding je pomalý

A hlavne:

Dokumentácia sa nedá škálovať.

Minimálny model riešenia

Používateľský manuál sa píše v dvoch vrstvách:

Core (štandard produktu)
Custom (odchýlky)

Každá vrstva má inú logiku.
A každá má svoju šablónu.

Šablóna č.1 – Core (hlavná vrstva)

Core sa píše tak, ako keby custom neexistoval.

Názov úlohy

Ako vytvoriť faktúru

Kedy túto funkciu použiť

Používa sa na vytvorenie novej faktúry pre zákazníka.

Kroky

Otvor Fakturáciu
Klikni na „Nová faktúra“
Vyplň údaje
Klikni na „Uložiť“

Výsledok

Faktúra sa uloží do systému a je pripravená na ďalšie spracovanie.

Obmedzenia / poznámky

faktúra musí obsahovať zákazníka
bez uloženia sa neobjaví v zozname

Šablóna č.2 – Custom (doplnková vrstva)

Custom sa píše ako odchýlka od Core.

Nikdy nie samostatne.

Pre koho platí

Platí pre klienta XY

Čo je inak

Pole „Stredisko“ je povinné.

Rozdiel oproti Core

V štandardnom systéme nie je toto pole povinné.

Dopad na používateľa

Faktúru nie je možné uložiť bez vyplnenia tohto poľa.

Ako tieto vrstvy spolu fungujú

Core je základ.

Custom ho len dopĺňa.

Nie naopak.

Príklad (správne použitie)

Core:

Faktúra sa po uložení zobrazí v zozname.

Custom:

Pre klienta XY musí byť faktúra pred zobrazením schválená.

Používateľ chápe:

čo je štandard
čo je výnimka
čo platí pre neho

Príklad (čo nefunguje)

Po vytvorení faktúry môže byť potrebné schválenie.

Nejasné:

kedy
pre koho
prečo

Mini checklist

Je Core šablóna čistá bez výnimiek?
Je Custom vždy označený „pre koho platí“?
Je jasne popísaný rozdiel oproti Core?
Vie používateľ, čo platí pre neho?
Dá sa text rozšíriť bez rozbitia existujúceho manuálu?

Prepojenie na kvalitu a workflow

Táto štruktúra nie je len o dokumentácii.

Ovplyvňuje:

testovanie (core vs custom scenáre)
support (čo je štandard vs výnimka)
onboarding (čo sa má nový človek naučiť)

Ak Core a Custom nie sú oddelené:

testovanie sa mení na hádanie
dokumentácia na chaos
produkt na zbierku výnimiek

Krátke zhrnutie

Univerzálna šablóna neznamená jeden text.

Znamená:

dve vrstvy, ktoré spolu dávajú zmysel.