Konzistentná terminológia, synonymá a skratky ako podmienka spoľahlivého vyhľadávania

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

Reálny problém z praxe

Pracovníčka supportu riešila používateľa, ktorý sa po niekoľkých neúspešných pokusoch nemohol prihlásiť do systému. Interného AI asistenta sa opýtala:

„Ako odblokujem používateľa po troch nesprávnych heslách?“

AI jej ponúkla postup na obnovenie zabudnutého hesla. Používateľ podľa neho dostal odkaz na vytvorenie nového hesla, ale ani po zmene sa do systému neprihlásil.

Support preto pokračoval v hľadaní. V používateľskom manuáli našiel kapitolu „Zmena zabudnutého hesla“. V administrátorskej príručke sa nachádzal postup „Reaktivácia konta“. V technickej dokumentácii bola rovnaká situácia opísaná ako „odstránenie príznaku LOCKED“. Starší incident používal výraz „odomknutie účtu“ a používateľské rozhranie zobrazovalo hlásenie „Konto bolo dočasne zablokované“.

Všetky zdroje opisovali tú istú oblasť systému, ale používali rozdielne výrazy:

používateľ,
účet,
konto,
používateľský profil,
blokovanie,
uzamknutie,
deaktivácia,
reaktivácia,
odblokovanie,
odomknutie.

Niektoré výrazy označovali rovnaký stav, iné iba podobný stav.

Dočasne uzamknutý účet po neúspešnom prihlásení nebol to isté ako účet, ktorý administrátor deaktivoval. Obnovenie hesla nebolo to isté ako odstránenie bezpečnostného blokovania. Reaktivácia konta mohla v jednom dokumente znamenať odblokovanie a v inom opätovné povolenie ručne deaktivovaného používateľa.

AI našla text, ktorý obsahoval slová „používateľ“, „prihlásenie“ a „heslo“. Nenašla však správny postup pre konkrétny stav účtu.

Dokumentácia existovala. Vyhľadávanie napriek tomu zlyhalo, pretože rovnaké veci nemali rovnaké názvy a podobné veci neboli dostatočne rozlíšené.

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

Problém nevznikol iba v AI asistentovi. Začal sa oveľa skôr, pri tvorbe projektovej terminológie.

Analytik použil pojem „používateľský účet“. V aplikácii vývojár pomenoval objekt UserProfile. Administrátorskú príručku písal niekto, kto používal slovo „konto“. Support si zvykol hovoriť „profil“ a v incidentoch sa objavovalo aj „login“.

Každý výraz bol v danom tíme zrozumiteľný. Naprieč projektom však chýbalo rozhodnutie, ktoré pomenovanie je hlavné, ktoré výrazy sú jeho povolené synonymá a ktoré označujú odlišný stav.

Pri bežnej komunikácii dokáže človek význam často odhadnúť z kontextu. Ak kolega povie „odblokuj mu profil“, skúsená pracovníčka supportu môže vedieť, čo tým myslí. Vyhľadávací systém však pracuje iba s informáciami, ktoré má k dispozícii.

Kľúčové slová môžu zlyhať preto, že otázka a dokument používajú rozdielne pomenovania. Významové vyhľadávanie dokáže niektoré podobné výrazy spojiť, ale môže zároveň priblížiť aj postupy, ktoré spolu tematicky súvisia, no riešia odlišný stav.

To sa stalo aj v našom prípade. Otázka o odblokovaní používateľa bola významovo blízka dokumentom o hesle, prihlásení, účte a bezpečnosti. Samotná podobnosť však nestačila na rozlíšenie medzi:

zabudnutým heslom,
dočasným uzamknutím po neúspešných pokusoch,
ručnou deaktiváciou používateľa,
zablokovaním z bezpečnostného dôvodu,
zrušením používateľského účtu.

Každá z týchto situácií potrebuje iný postup.

Podobný problém vzniká pri skratkách. Dokumentácia môže používať označenia MFA, 2FA alebo viacfaktorové overenie. V konkrétnom produkte môžu MFA a 2FA označovať rovnakú funkciu, ale nemusia. Skratka OTP môže znamenať jednorazové heslo, pričom používateľ sa môže opýtať na „SMS kód“ alebo „overovací kód“.

Ak dokumentácia neobsahuje väzby medzi týmito výrazmi, relevantný postup sa nemusí nájsť. Ak ich naopak systém bez kontroly považuje za úplne zameniteľné, môže spojiť rozdielne funkcie.

Konzistentná terminológia preto neznamená zakázať prirodzený jazyk a všade mechanicky opakovať jednu frázu. Znamená vytvoriť riadený vzťah medzi výrazmi:

ktorý pojem je preferovaný,
čo presne znamená,
ktoré synonymá možno pri vyhľadávaní považovať za rovnocenné,
ktoré podobné výrazy sa nesmú zamieňať,
ako sa rozvíjajú skratky,
pre ktorý produkt, modul alebo zákazníka dané pomenovanie platí.

Bez týchto väzieb sa vyhľadávanie spolieha na odhad.

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

Nekonzistentné pomenovania vyzerajú ako redakčný problém. V prevádzke však vytvárajú konkrétne náklady.

Čas
Support skúša viacero otázok, prechádza výsledky a otvára dokumenty, ktoré riešia inú situáciu. Ak správny postup nenájde, obracia sa na administrátora, testerku alebo vývojára.
Chaos
Rôzne tímy začnú používať vlastné slovníky. Rovnaký výraz môže mať v špecifikácii, aplikácii, testoch a manuáloch odlišný význam. Pri incidente potom nie je jasné, či ľudia hovoria o rovnakom stave.
Riziko nesprávneho zásahu
Obnovenie hesla namiesto odstránenia blokovania problém nevyrieši. Reaktivácia ručne deaktivovaného používateľa môže byť bezpečnostným incidentom, ak bol účet vypnutý zámerne.
Falošné bugy
Testerka môže nahlásiť, že systém nezodpovedá dokumentácii, hoci porovnáva dve rozdielne funkcie pomenované podobným výrazom. Alebo skutočnú chybu nenahlási, pretože rozdiel v názvoch považuje iba za synonymum.
Slabý onboarding
Nový človek nevie, že „konto“ v administrátorskej príručke, „používateľský účet“ v špecifikácii a UserProfile v technickej dokumentácii označujú ten istý objekt. Musí si tieto vzťahy postupne zistiť od seniorov.
Nespoľahlivá AI odpoveď
AI môže nájsť tematicky podobný text a vytvoriť z neho presvedčivý postup. Jazyková plynulosť potom zakryje, že zdroj opisuje iný stav, inú funkciu alebo inú verziu produktu.

Nekonzistentná terminológia sa môže aj ďalej rozmnožovať. Ak support uloží nesprávnu odpoveď ako nový postup, do znalostnej bázy pribudne ďalšie pomenovanie a ďalší zdroj, ktorý sa bude pri budúcom vyhľadávaní miešať s ostatnými.

Minimálny model riešenia

Projekt nepotrebuje na začiatku rozsiahly firemný slovník. Potrebuje minimálny terminologický register, ktorý bude použiteľný pri písaní dokumentácie aj pri vyhľadávaní.

Pre každý dôležitý pojem by mal register obsahovať aspoň:

Preferovaný názov
Pomenovanie, ktoré sa má používať v nových dokumentoch, názvoch kapitol a používateľskom rozhraní, ak tomu nebráni technický alebo zmluvný dôvod.
Jednoznačný význam
Krátke vysvetlenie, čo pojem v danom produkte označuje.
Povolené synonymá
Výrazy, ktoré môže používateľ zadať pri vyhľadávaní a ktoré možno bezpečne spojiť s preferovaným názvom.
Výrazy, ktoré sa nesmú zamieňať
Podobné pojmy s odlišným významom alebo postupom.
Skratka a jej úplný názov
Skratka sa má pri prvom použití vysvetliť. Register má zachytiť aj bežné varianty, s ktorými sa možno stretnúť v otázkach a starších dokumentoch.
Rozsah platnosti
Produkt, modul, verzia, prostredie, Core alebo Custom charakter a prípadne zákazník, pre ktorého terminológia platí.
Príklad použitia
Krátka veta ukazujúca, ako má byť pojem použitý v dokumentácii alebo v názve postupu.
Vlastník
Rola alebo tím, ktorý rozhoduje o význame a schvaľuje zmeny.

Pre situáciu s používateľským účtom by minimálny záznam mohol vyzerať takto:

Preferovaný názov: dočasne uzamknutý používateľský účet
Význam: účet automaticky uzamknutý po prekročení povoleného počtu neúspešných prihlásení
Povolené vyhľadávacie synonymá: zablokovaný účet po nesprávnom hesle, odblokovanie účtu, odomknutie používateľa
Súvisiace výrazy, ktoré sa nesmú zameniť: deaktivovaný účet, zrušený účet, zabudnuté heslo, bezpečnostne zablokovaný účet
Technické označenie: LOCKED
Platnosť: Core, modul Správa používateľov, od verzie 4.2
Vlastník: tím Identity and Access Management

Samotný register však nestačí. Jeho obsah sa musí premietnuť do dokumentácie a vyhľadávania.

Praktický minimálny postup môže byť takýto:

Vyberú sa pojmy, ktoré majú v projekte viac názvov alebo môžu ovplyvniť vykonanie postupu.
Pre každý pojem sa určí preferovaný názov a presný význam.
Bezpečné synonymá sa evidujú ako vyhľadávacie aliasy.
Podobné, ale odlišné pojmy sa výslovne označia ako nezameniteľné.
Skratka sa prepojí s úplným názvom a bežnými používateľskými pomenovaniami.
Nové alebo upravené dokumenty používajú preferované názvy.
Staršie dokumenty sa nemusia okamžite celé prepísať, ale ich výrazy sa prepoja s aktuálnou terminológiou.
Vyhľadávanie sa testuje otázkami formulovanými terminológiou používateľa, supportu aj technického tímu.

Názov dokumentu alebo obsahového bloku by mal obsahovať preferovaný pojem a dostatočný kontext.

Namiesto všeobecného názvu:

„Problémy s používateľom“

je použiteľnejší názov:

„Odblokovanie dočasne uzamknutého používateľského účtu po neúspešnom prihlásení“

V samotnom texte možno uviesť aj prirodzené synonymá:

„Tento postup sa používa pri dočasne uzamknutom používateľskom účte, ktorý môže používateľ označiť aj ako zablokovaný alebo zamknutý účet. Nevzťahuje sa na účet, ktorý administrátor ručne deaktivoval.“

Takýto zápis pomáha človeku aj vyhľadávaniu. Zároveň chráni pred použitím postupu na podobnú, ale odlišnú situáciu.

Skratky je vhodné pri prvom použití zapísať spolu s úplným názvom:

„Viacfaktorové overenie (MFA)“

Ak používatelia bežne hľadajú aj „dvojfaktorové overenie“, „2FA“, „SMS kód“ alebo „overovací kód“, treba určiť, ktoré z týchto výrazov sú v konkrétnom produkte synonymá a ktoré označujú iba jeden spôsob overenia.

Nie každý rozdiel v terminológii treba odstrániť. Technická dokumentácia môže potrebovať názov databázového poľa alebo systémového stavu, zatiaľ čo používateľský manuál používa názov z obrazovky. Medzi týmito názvami však musí existovať dohľadateľná väzba.

Používateľské označenie „Dočasne zablokované konto“ môže byť preto prepojené s:

preferovaným projektovým pojmom „dočasne uzamknutý používateľský účet“,
systémovým stavom LOCKED,
príslušným administrátorským postupom,
chybovým hlásením z aplikácie,
testovacími prípadmi pre odblokovanie.

Cieľom nie je, aby všetci ľudia v každej situácii používali identickú vetu. Cieľom je, aby projekt vedel, ktoré výrazy označujú tú istú vec a ktoré už nie.

Prepojenie na kvalitu a workflow

Terminologický register nesmie vzniknúť až pri nahrávaní dokumentov do znalostnej bázy. V tom čase už môžu byť nekonzistentné názvy rozšírené v požiadavkách, aplikácii, testoch, manuáloch aj incidentoch.

Terminológia má prechádzať celým workflow projektu.

V user story sa použije preferovaný názov objektu alebo funkcie.

Akceptačné kritériá presne rozlíšia stavy, ktoré vedú k odlišnému správaniu. Dočasné uzamknutie účtu sa nesmie zameniť s jeho ručnou deaktiváciou.

Špecifikácia prepojí používateľský názov so systémovým označením, stavmi, chybovými hláseniami a pravidlami.

Vývoj zachová dohodnuté názvy v používateľskom rozhraní, API a udalostiach, prípadne zdokumentuje technické odlišnosti.

Testovacie prípady používajú rovnaké pojmy a overujú aj hranice medzi podobnými stavmi.

Používateľská, administrátorská, support a technická dokumentácia prevezmú preferovanú terminológiu alebo uvedú väzbu na svoje špecifické pomenovanie.

Release notes použijú názov, ktorý možno prepojiť s funkciou, dokumentáciou a zmenou v produkte.

Pri spracovaní pre AI sa synonymá, skratky a nezameniteľné pojmy zachovajú ako súčasť vyhľadávacích pravidiel a metadát.

Do Definition of Done možno zaradiť formuláciu:

„Nové a zmenené názvy funkcií, objektov, stavov a skratiek sú v súlade s terminologickým registrom. Nové synonymá a technické označenia sú zaznamenané a prepojené s preferovaným pojmom. Podobné pojmy s rozdielnym významom sú v dokumentácii jednoznačne rozlíšené. Vyhľadávanie bolo overené pomocou používateľských, supportných a technických formulácií otázky.“

Ako testerka by som nekontrolovala iba to, či AI našla odpoveď pri použití presného názvu z dokumentácie.

Pre postup odblokovania by som použila napríklad tieto otázky:

Ako odblokujem používateľa po troch nesprávnych heslách?
Čo mám urobiť so zamknutým kontom?
Ako odstránim stav LOCKED?
Používateľ si zmenil heslo, ale stále sa nemôže prihlásiť.
Je odomknutie účtu rovnaké ako reaktivácia deaktivovaného používateľa?
Môžem obnoviť prístup používateľovi, ktorého účet bol vypnutý administrátorom?

Správny výsledok neznamená, že AI vždy poskytne rovnaký postup.

Pri prvých štyroch otázkach má nájsť postup pre dočasne uzamknutý účet. Pri otázkach o deaktivovanom používateľovi má rozpoznať odlišný stav. Ak nemá dostatok kontextu, má si vyžiadať doplnenie informácie namiesto automatického výberu jedného z podobných návodov.

Ak sa zmení názov funkcie alebo stav v aplikácii, zmena sa nesmie skončiť úpravou textu na obrazovke. Treba skontrolovať:

terminologický register,
používateľské a administrátorské návody,
support dokumentáciu,
technickú dokumentáciu,
testovacie prípady,
release notes,
vyhľadávacie synonymá,
referenčné otázky pre testovanie AI,
staršie názvy, ktoré budú používatelia ešte určitý čas zadávať.

Nové pomenovanie nemusí okamžite zrušiť staré synonymum. Starý výraz môže zostať ako vyhľadávací alias, ale výsledok má používateľa priviesť k aktuálnemu pojmu a aktuálnemu postupu.

Krátke zhrnutie

Spoľahlivé vyhľadávanie nezačína pri AI modeli. Začína pri tom, ako projekt pomenúva funkcie, objekty, stavy a postupy.

Ak jedna vec používa viac názvov bez zaznamenaného vzťahu, správny dokument sa nemusí nájsť. Ak sa podobné pojmy považujú za synonymá bez kontroly, môže sa nájsť nesprávny postup.

Minimálny terminologický register preto potrebuje určiť:

preferovaný názov,
jednoznačný význam,
bezpečné synonymá,
podobné pojmy, ktoré sa nesmú zamieňať,
skratky a ich úplné názvy,
technické a používateľské označenia,
rozsah platnosti,
vlastníka pojmu.

Terminológia musí zostať konzistentná od user story a špecifikácie cez systém, testy a manuály až po znalostnú bázu pre AI.

Ak sa zmení systémový pojem, musí sa spolu s ním zmeniť dokumentácia, vyhľadávacie väzby aj testovacie otázky.

Dokumentácia nie je vyhľadateľná iba preto, že sa v nej nachádzajú správne informácie. Vyhľadateľná je vtedy, keď používateľ dokáže túto informáciu nájsť aj slovami, ktoré pri riešení problému skutočne používa, bez toho, aby dostal postup pre podobnú, ale odlišnú situáciu.