Séria: Ako písať dokumentáciu a manuály v IT projekte
V predchádzajúcich článkoch sme si ukázali dve veci:
- prečo manuál nie je univerzálny dokument,
- a čo sa deje vo firmách, kde dokumentácia neexistuje.
Teraz sa pozrime na problém, ktorý je menej viditeľný – ale v produktových firmách veľmi častý.
Rozdiel medzi Core funkcionalitou produktu a klientskymi úpravami (Custom).
Reálny problém z praxe
Tester testuje novú funkcionalitu.
Zistí, že u jedného klienta sa systém správa inak.
Opýta sa:
„Je to bug alebo feature?“
Odpoveď znie:
„To má klient XY upravené.“
Lenže:
- v dokumentácii to nie je,
- v špecifikácii to nie je,
- v manuáli to nie je,
- support o tom nevie.
Výsledok?
Tester nahlási bug.
Vývojár ho zavrie ako „expected behaviour“.
Support sľúbi funkciu inému klientovi.
Nový kolega netuší, čo je štandard produktu.
Produkt existuje.
Mapa produktu nie.
Čo sa tu vlastne pokazilo (analýza systému)
V produktových firmách často vzniká tento model:
- Existuje core verzia produktu
- Pre klientov sa robia custom úpravy
- Tieto úpravy sa postupne miešajú do dokumentácie
A po čase už nikto nevie:
- čo je štandardná funkcionalita,
- čo je klientská výnimka,
- čo je dočasný workaround,
- čo je plánované do core produktu.
Dokumentácia potom opisuje mix reality.
A práve tu začína chaos.
Ako to vyzerá v realite
- Falošné bugy
Tester vidí funkcionalitu, ktorá nie je popísaná.
Je to:
- bug?
- klientská úprava?
- experiment?
- historická výnimka?
Bez jasného rozdelenia Core vs Custom sa testovanie mení na hádanie.
2. Support sľubuje niečo, čo produkt nemá
Support pracuje s dokumentáciou.
Ak v nej nie je jasne označené, že ide o klientskú úpravu, môže ju považovať za štandard.
A potom vzniká situácia:
„Ale klient XY to má.“
Lenže to nie je feature produktu.
Je to zákazková úprava.
3. Produkt sa potichu rozpadá
Keď sa výnimky miešajú do dokumentácie, vzniká efekt:
produkt sa rozpadá na desiatky špecifických scenárov.
Vývoj začne riešiť:
- klient A
- klient B
- klient C
A Core logika sa postupne stráca.
4. Onboarding nových kolegov je chaos
Nový tester alebo developer potrebuje vedieť:
- čo je štandard produktu
- čo je klientská výnimka
- čo je experiment
- čo je historický workaround
Ak to dokumentácia neobsahuje, onboarding prebieha cez otázky seniorom.
A systém sa opäť stáva závislým na ľuďoch.
Minimálny model riešenia
Riešenie je prekvapivo jednoduché.
Nie je to technológia.
Je to disciplína.
1. Oddeliť Core dokumentáciu od klientských úprav
Dokumentácia produktu má obsahovať:
- štandardné funkcionality
- oficiálne workflow
- podporované scenáre
Klientské úpravy majú byť:
- v samostatnej sekcii
- alebo v samostatnom dokumente.
2. Označovať rozsah funkcionality
Veľmi pomáhajú jednoduché označenia:
- dostupné v core produkte
- dostupné len pre klienta XY
- voliteľný modul
- experimentálna funkcionalita
Nový kolega tak okamžite vidí rozsah.
3. Rozlišovať Core vs Custom už v špecifikácii
Ak sa to nerozlíši na začiatku projektu, problém sa prenesie:
špecifikácia → implementácia → testy → dokumentácia → support.
Preto je dôležité označiť rozsah funkcionality už pri zadávaní.
Prepojenie na kvalitu produktu
Core vs Custom nie je len dokumentačný detail.
Je to produktová architektúra.
Ak dokumentácia neukazuje hranicu medzi:
- produktom
- zákazkovým riešením
firma môže stratiť prehľad o vlastnom produkte.
A to je moment, keď sa produktová firma začne meniť na zákazkovú dielňu.
Krátke zhrnutie
Ak dokumentácia nerozlišuje Core a Custom, vznikajú:
- falošné bugy
- mylné očakávania klientov
- chaos v supporte
- závislosť na senioroch
- postupný rozpad produktu
Dokumentácia tu neplní len informačnú funkciu.
Je to mapa produktu.