Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
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.
Manuál to nikde nehovorí.
A všetci majú pocit, že ten druhý robí chybu.
Čo sa tu vlastne pokazilo (analýza systému)
V manuáli je zmiešané:
- čo je štandard produktu (Core)
- čo je úprava pre konkrétneho klienta (Custom)
Používateľ to nedokáže rozlíšiť.
Typická realita:
- jedna kapitola popisuje „všetko dokopy“
- bez označenia, pre koho to platí
- bez vysvetlenia rozdielov
To vytvára falošné očakávania.
A to je presne to, čo potom rieši support.
Skutočné náklady (čas, chaos, riziko)
- používateľ očakáva funkcionalitu, ktorú nemá
- support vysvetľuje rozdiely namiesto riešenia problémov
- tester reportuje „neexistujúce bugy“
- onboarding nových ľudí je pomalý
A hlavne:
Nikto nevie presne povedať, čo je vlastne produkt.
Minimálny model riešenia
Najdôležitejšie pravidlo:
Používateľský manuál musí byť postavený na Core.
Custom nesmie byť zamiešaný do základného textu.
1. Core manuál = pravda produktu
Core manuál obsahuje:
- štandardné funkcionality
- základné scenáre
- správanie, ktoré platí pre všetkých
Bez výnimiek.
Bez klientov.
Bez „niekde to funguje inak“.
2. Custom = odchýlka, nie súčasť Core
Custom funkcionalita má byť:
- oddelená
- jasne označená
- viazaná na konkrétny kontext
Nie ako súčasť hlavného textu.
3. Prečo to nemiešať
Zmiešaný manuál:
Po vytvorení faktúry môže byť potrebné schválenie.
Používateľ nevie:
- kedy
- pre koho
- prečo
Oddelený prístup:
Core:
Faktúra sa po uložení zobrazí v zozname.
Custom (samostatne):
Pre klienta XY:
Faktúra musí byť schválená pred ďalším spracovaním.
4. Prepojovací princíp (minimum v user manuáli)
Používateľský manuál môže obsahovať len jemnú informáciu:
Správanie sa môže líšiť podľa konfigurácie systému.
Detail patrí inde:
- do admin dokumentácie
- do support dokumentácie
- do klientského manuálu
5. Príklad (čo funguje vs čo nie)
Neefektívne:
Export je dostupný pre niektorých používateľov.
Nejasné, kto, kedy, prečo.
Funguje:
Core:
Export umožňuje stiahnuť dáta do súboru.
Custom:
Pre klienta XY je export rozšírený o formát XML.
Mini checklist
- Je Core manuál čistý bez klientských výnimiek?
- Vie používateľ, že číta štandard produktu?
- Sú custom úpravy oddelené, nie zamiešané?
- Je jasné, čo platí vždy a čo len niekde?
Prepojenie na kvalitu a workflow
Core vs Custom nie je len dokumentačná téma.
Je to:
- produktové rozhodnutie
- testerská téma
- support téma
- základ pre AI a automatizáciu
Ak to nie je oddelené:
- testovanie sa mení na hádanie
- support na vysvetľovanie
- dokumentácia na chaos
A to sa vždy prejaví v kvalite produktu.
Krátke zhrnutie
Používateľský manuál má odpovedať na otázku:
„Čo systém robí pre mňa?“
Nie:
„Čo robí pre niekoho iného.“
Core je definícia produktu.
Custom je odchýlka.
Ak sa to mieša,
nevzniká flexibilita.
Vzniká chaos.