Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Pracovníčka supportu sa interného AI asistenta opýtala:
„Ako môžem zákazníkovi znovu vystaviť faktúru?“
AI odpovedala konkrétnym postupom:
- Otvorte detail objednávky.
- Prejdite do časti Fakturácia.
- Vyberte možnosť Znovu vystaviť faktúru.
- Skontrolujte fakturačné údaje.
- Potvrďte vystavenie a odoslanie nového dokladu.
Odpoveď vyzerala dôveryhodne. Používala správne názvy obrazoviek, obsahovala logické kroky a odkazovala na aktuálny používateľský manuál.
Pre daného zákazníka však bola nesprávna.
Všeobecný postup opisoval Core riešenie vo verzii 5.4. Zákazník ALFA používal verziu 5.2 s klientskou úpravou, v ktorej faktúry nevytváral hlavný systém. Vystavovali sa cez externú účtovnú integráciu.
Ak by pracovníčka supportu použila odporúčaný Core postup, mohla vytvoriť druhý doklad s iným číslom alebo odoslať faktúru, ktorá nebola zaevidovaná v účtovnom systéme zákazníka.
AI teda nenašla nezmyselný ani zastaraný dokument. Našla správny a aktuálny postup, ktorý však platil pre iné riešenie.
V znalostnej báze sa nachádzali štyri podobné zdroje:
- aktuálny Core postup pre verziu 5.4,
- starší Core postup pre verziu 5.2,
- Custom postup pre zákazníka ALFA,
- Custom postup pre zákazníka BETA.
Všetky obsahovali rovnaké pojmy: faktúra, objednávka, opätovné vystavenie a odoslanie. Bez informácie o zákazníkovi, verzii a type riešenia ich AI považovala za možné odpovede na rovnakú otázku.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nevznikol preto, že by bol návod napísaný nezrozumiteľne. Vznikol preto, že znalostná báza nerozlišovala kontext, v ktorom sa jednotlivé návody môžu použiť.
V produktovej firme nemusí existovať iba jedna odpoveď na otázku „Ako funguje táto funkcia?“.
Správna odpoveď môže závisieť od:
- produktu a modulu,
- Core alebo Custom riešenia,
- konkrétneho zákazníka,
- nasadenej verzie,
- prostredia,
- konfigurácie alebo zapnutého feature flagu.
Core opisuje spoločné správanie produktu. Custom opisuje odchýlku, ktorá platí iba pre určeného zákazníka alebo skupinu zákazníkov.
Samotné označenie Custom však nestačí. Dvaja zákazníci môžu mať rovnakú funkciu upravenú rozdielnym spôsobom. Rovnako nestačí uviesť iba meno zákazníka, ak používal viac verzií systému alebo ak sa jeho úprava časom zmenila.
V znalostnej báze tak môžu existovať napríklad tieto informácie:
- Core, verzia 5.4: faktúru možno znovu vystaviť v administrácii.
- Core, verzia 5.2: existujúcu faktúru možno iba znovu odoslať.
- Custom ALFA, verzia 5.2: faktúru spracúva externá účtovná integrácia.
- Custom BETA, verzia 5.4: opätovné vystavenie faktúry musí schváliť finančné oddelenie.
Každá z týchto informácií môže byť správna. Nemôžu sa však používať ako zameniteľné odpovede.
Ak otázka neobsahuje zákazníka ani verziu, AI nemá dostatok údajov na bezpečný výber postupu.
Častou chybou je, že napriek tomu odpovie. Vyberie zdroj s najväčšou významovou podobnosťou, najnovším dátumom alebo najpodrobnejším návodom.
Ani jedno z týchto kritérií však nepotvrdzuje, že postup platí pre konkrétny prípad.
Novší Core dokument nemusí nahrádzať staršiu Custom dokumentáciu. Podrobnejší návod pre zákazníka BETA nemusí byť použiteľný pre zákazníka ALFA. Rovnaký názov funkcie nemusí v dvoch verziách označovať rovnaké správanie.
Ešte väčší problém vzniká, keď AI poskladá odpoveď z viacerých zdrojov.
Môže prevziať začiatok postupu z Core manuálu, schvaľovací krok z Custom dokumentácie zákazníka BETA a upozornenie zo starého incidentu zákazníka ALFA.
Výsledná odpoveď je gramaticky správna a pôsobí ucelene. V skutočnosti však neopisuje žiadne existujúce riešenie.
Ako testerka by som preto nekontrolovala iba to, či AI našla správne kroky. Kontrolovala by som aj to, či všetky časti odpovede patria k rovnakému zákazníkovi, rovnakej verzii a rovnakému typu riešenia.
Skutočné náklady (čas, chaos, riziko)
Miešanie odpovedí sa často prejaví až pri vykonávaní odporúčaného postupu.
Pracovníčka supportu najprv hľadá tlačidlo, ktoré sa v zákazníkovej verzii nenachádza. Potom kontaktuje testerku alebo vývojára. Tí začnú zisťovať, aké riešenie má zákazník nasadené a či ide o Core alebo Custom správanie.
Následne sa prehľadávajú:
- staré tikety,
- release notes,
- zákaznícke špecifikácie,
- poznámky k nasadeniu,
- konfiguračné tabuľky,
- informácie od ľudí, ktorí si ešte pamätajú históriu úpravy.
Vznikajú tri druhy nákladov.
- Čas
Rýchla odpoveď AI sa musí ručne overovať. Namiesto skrátenia riešenia incidentu vznikne ďalšie kolo hľadania a konzultácií.
- Chaos
Každý člen tímu môže pracovať s inou verziou postupu. Jeden vychádza z Core manuálu, druhý zo zákazníckej špecifikácie a tretí zo starého incidentu.
- Riziko
Nesprávny postup môže zmeniť údaje, spustiť nepovolenú operáciu alebo obísť zákaznícky proces. Pri fakturácii, platbách alebo prístupových právach môže mať chybná odpoveď prevádzkový, finančný alebo bezpečnostný dopad.
Problém sa môže ďalej šíriť.
Ak support vyrieši incident pomocou zmiešanej odpovede a tento postup následne uloží ako novú znalostnú položku, do dokumentácie pribudne ďalší zdroj bez jasného kontextu.
Chyba už nie je iba jednorazovým omylom AI. Stáva sa súčasťou znalostnej bázy a môže sa opakovať v ďalších odpovediach, tiketoch aj manuáloch.
Minimálny model riešenia
Znalostná báza musí pri každom samostatne vyhľadateľnom postupe uchovávať údaje, podľa ktorých možno určiť, pre koho a za akých podmienok platí.
Minimálny model môže obsahovať:
| Pole | Príklad hodnoty |
|---|---|
| Produkt | Objednávkový systém |
| Modul | Fakturácia |
| Typ riešenia | Core alebo Custom |
| Zákazník | Všetci zákazníci alebo ALFA |
| Verzia od | 5.2 |
| Verzia do | 5.2.9 |
| Prostredie | Produkcia |
| Konfigurácia | Integrácia FIN-ALFA aktívna |
| Stav | Platné |
| Vlastník | Tím fakturácie |
| Posledné overenie | 3. 9. 2026 |
| Nahradené zdrojom | Postup pre verziu 5.4 |
Tieto údaje nemajú slúžiť iba na zobrazenie pri citácii. Musia ovplyvniť výber zdrojov ešte pred vytvorením odpovede.
Minimálny postup môže fungovať takto:
- Systém určí, ktorého produktu a modulu sa otázka týka.
- Zistí konkrétneho zákazníka.
- Zistí nasadenú verziu.
- Overí, či zákazník používa Core alebo Custom riešenie.
- Skontroluje relevantnú konfiguráciu alebo feature flag.
- Vyhľadá iba zdroje platné pre tento kontext.
- Overí, či si vybrané zdroje navzájom neodporujú.
- Až potom vytvorí odpoveď.
Ak sa používateľ opýta:
„Ako znovu vystavím faktúru zákazníkovi ALFA vo verzii 5.2?“
vyhľadávanie možno obmedziť takto:
| Kritérium | Požadovaná hodnota |
|---|---|
| Produkt | Objednávkový systém |
| Modul | Fakturácia |
| Zákazník | ALFA |
| Verzia | 5.2 |
| Prostredie | Produkcia |
| Stav dokumentu | Platné |
Pri zákazníckej úprave má mať Custom pravidlo prednosť pred všeobecným Core pravidlom iba v rozsahu, ktorý skutočne mení.
To neznamená, že pri zákazníkovi s Custom úpravou sa má ignorovať celá Core dokumentácia. Väčšina systému môže stále fungovať podľa spoločných pravidiel.
Custom dokumentácia preto musí pomenovať:
- ktorú časť Core správania mení,
- od ktorej verzie zmena platí,
- či Core postup nahrádza celý alebo iba jeho časť,
- ktoré kroky zostávajú bez zmeny,
- od akej konfigurácie úprava závisí,
- či má úprava obmedzenú platnosť.
Všeobecná poznámka:
„Zákazník ALFA má vlastné spracovanie faktúr.“
nestačí.
Použiteľný záznam môže vyzerať takto:
„Pre zákazníka ALFA vo verziách 5.2 až 5.2.9 nahrádza Custom úprava Core kroky 2 až 4. Faktúru nevystavuje objednávkový systém, ale účtovná integrácia FIN-ALFA. Kontrolu a opätovné odoslanie vykonáva finančné oddelenie podľa postupu FA-12.“
Ak systém nepozná zákazníka alebo verziu, nemá si chýbajúci údaj domyslieť.
Môže odpovedať:
„Našla som rozdielne postupy pre Core riešenie a zákaznícke úpravy. Na výber správneho postupu potrebujem názov zákazníka a verziu systému.“
Ak pozná zákazníka, ale nie verziu, vhodná odpoveď môže znieť:
„Pre zákazníka ALFA existujú dva postupy. Jeden platí pre verziu 5.2 a druhý od verzie 5.4. Bez potvrdenia nasadenej verzie neviem bezpečne určiť správny postup.“
Ak nájde konfliktné zdroje s rovnakou platnosťou, nemá konflikt vyriešiť odhadom. Má ho pomenovať a odkázať na vlastníka dokumentácie alebo zodpovedný tím.
Nevytvorenie jednoznačného návodu nie je v takejto situácii zlyhaním AI. Je to ochrana pred použitím nesprávneho kontextu.
Prepojenie na kvalitu a workflow
Rozlíšenie Core, Custom, verzie a zákazníka sa nesmie dopĺňať až pri nahrávaní dokumentov do AI nástroja. Musí vzniknúť spolu s požiadavkou a zostať zachované počas celého životného cyklu zmeny.
Tok informácie môže vyzerať takto:
User story určí, či ide o spoločnú alebo zákaznícku požiadavku.
Akceptačné kritériá opíšu rozdiel medzi Core a Custom správaním.
Špecifikácia určí zákazníka, podporované verzie, konfiguráciu a dotknuté procesy.
Implementácia zachová väzbu medzi zmenou a požiadavkou.
Testovacie prípady overia Core aj príslušné Custom varianty.
Používateľská, administrátorská, support a technická dokumentácia prevezmú rovnaké označenie rozsahu.
Release notes určia, v ktorej verzii bola zmena nasadená.
Znalostná báza pre AI prevezme informáciu o zákazníkovi, verzii a platnosti spolu s obsahom dokumentu.
Pri vzniku Custom požiadavky sa má zaznamenať:
- od ktorého Core správania sa riešenie odlišuje,
- ktorého zákazníka sa zmena týka,
- pre ktorú verziu vznikla,
- ktoré procesy a dokumenty ovplyvňuje,
- kto zodpovedá za zákaznícku dokumentáciu.
Pri nasadení novej verzie sa musí overiť:
- či Custom úprava zostáva aktívna,
- či sa stala súčasťou Core riešenia,
- či ju nové Core správanie nenahradilo,
- či sa nezmenil rozsah zákazníkov,
- či staré postupy nezostali označené ako platné,
- či sa aktualizované údaje dostali aj do znalostnej bázy pre AI.
Do Definition of Done možno zaradiť formuláciu:
„Dokumentácia zmeny jednoznačne určuje produkt, modul, Core alebo Custom charakter, dotknutého zákazníka, rozsah verzií, relevantnú konfiguráciu a stav platnosti. Pri Custom riešení je uvedené, ktorú časť Core správania nahrádza alebo dopĺňa. Zmenené zdroje boli aktualizované v znalostnej báze a staré verzie boli označené ako nahradené alebo archivované.“
Samostatnou súčasťou testovania má byť kontrola odpovedí v rôznych kontextoch.
| Testovací kontext | Očakávaný výsledok |
|---|---|
| Core, verzia 5.4 | AI použije aktuálny Core postup |
| Core, verzia 5.2 | AI použije Core postup platný pre verziu 5.2 |
| Zákazník ALFA, verzia 5.2 | AI použije Custom postup pre integráciu FIN-ALFA |
| Zákazník BETA, verzia 5.4 | AI použije Custom schvaľovací proces zákazníka BETA |
| Neznámy zákazník | AI si vyžiada identifikáciu zákazníka |
| Neznáma verzia s viacerými postupmi | AI upozorní na nejednoznačnosť |
| Konfliktné zdroje | AI pomenuje konflikt a nevytvorí odpoveď odhadom |
| Zmiešané zdroje z rôznych kontextov | AI ich nepoužije v jednej odpovedi |
Test nemá overovať iba to, či AI našla správnu informáciu. Musí overiť aj to, či nepoužila informáciu z nesprávneho kontextu.
Pri odpovedi by malo byť možné zistiť:
- pre ktorý produkt a modul platí,
- či opisuje Core alebo Custom riešenie,
- ktorého zákazníka sa týka,
- pre ktorú verziu bola vytvorená,
- akú konfiguráciu predpokladá,
- z ktorých zdrojov vznikla,
- či sa v nej nespojili nezlučiteľné postupy.
Ak sa zmení systém, musí sa spolu s ním zmeniť aj dokumentácia a zdroje pre AI. Inak môže nová verzia produktu fungovať správne, ale AI bude používateľom naďalej odporúčať staré alebo zákaznícky cudzie postupy.
Krátke zhrnutie
Core, Custom, verzia a zákazník nie sú doplnkové údaje k odpovedi. Určujú, či je odpoveď vôbec použiteľná.
Nestačí, aby AI našla text, ktorý sa podobá na otázku. Musí poznať kontext, vyhľadať iba zdroje platné pre tento kontext a zabrániť spájaniu nezlučiteľných postupov.
Tento kontext musí vznikať už v user story a špecifikácii. Následne sa musí zachovať v testoch, manuáloch, release notes aj znalostnej báze.
Ak chýba zákazník, verzia alebo rozsah úpravy, správnym výsledkom nemusí byť návod. Správnym výsledkom môže byť požiadavka na doplnenie údajov.
Spoľahlivá znalostná báza neodpovedá iba na otázku „Čo treba urobiť?“. Dokáže určiť aj to, pre koho, v ktorej verzii a za akých podmienok daný postup platí.