Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Pracovníčka supportu riešila objednávku, ktorá po úspešnej platbe zostala v stave Čaká na platbu. Interného AI asistenta sa opýtala:
„Ako máme opraviť stav objednávky po úspešnej platbe?“
AI našla konkrétny postup:
- Skontrolovať výsledok platby v platobnej bráne.
- V administrácii manuálne zmeniť stav objednávky.
- Vypnúť automatickú kontrolu platobného stavu.
- Spustiť synchronizáciu objednávky znova.
Odpoveď bola presná, zrozumiteľná a obsahovala aj názov konfiguračného parametra.
Mala však zásadný problém. Postup pochádzal z poznámky k incidentu starého dva roky. Platila iba pre testovacie prostredie, pre verziu systému 3.6 a pre klientsku úpravu zákazníka ABC. Po oprave chyby už nebol tento zásah povolený.
V aktuálnej produkčnej verzii sa objednávka nemala opravovať manuálne. Support mal incident eskalovať integračnému tímu, pretože manuálna zmena mohla oddeliť stav objednávky od skutočného výsledku platby.
AI našla informáciu, ktorá obsahovo zodpovedala otázke. Nevedela však:
- odkiaľ informácia pochádza,
- kto ju vytvoril,
- prečo vznikla,
- pre ktoré prostredie platila,
- ktorej verzie systému sa týkala,
- či išlo o Core alebo Custom riešenie,
- či bola neskôr nahradená,
- či bola ešte povolená na použitie.
Samotný text postupu bol zrozumiteľný. Chýbali mu metadáta a dôveryhodný pôvod.
Čo sa tu vlastne pokazilo (analýza systému)
AI vyhľadala text podľa významovej podobnosti. V otázke aj v starom incidente sa nachádzali rovnaké pojmy: úspešná platba, nesprávny stav objednávky, synchronizácia a manuálna oprava.
Z pohľadu vyhľadávania išlo o relevantný výsledok. Z pohľadu projektu však išlo o nesprávny zdroj.
Obsah dokumentu hovorí, čo je v ňom napísané. Metadáta hovoria, v akom kontexte možno túto informáciu použiť.
Bez metadát vyzerajú pre AI rovnako dôveryhodne:
- schválená funkčná špecifikácia,
- aktuálny používateľský manuál,
- komentár vývojára v Jire,
- poznámka zo stretnutia,
- dočasný workaround z incidentu,
- odpoveď v starom support tikete,
- archivovaná verzia dokumentu,
- text vytvorený inou AI.
Tieto zdroje však nemajú rovnakú váhu.
Schválená špecifikácia môže určovať očakávané správanie systému. Komentár v Jire môže byť iba pracovná hypotéza. Zápis zo stretnutia môže zachytávať návrh, ktorý nebol schválený. Incident môže opisovať výnimočný zásah vykonaný pred opravou chyby.
Ak všetky tieto informácie skončia v znalostnej báze bez označenia pôvodu, AI nedokáže spoľahlivo rozlíšiť:
- pravidlo od názoru,
- schválené rozhodnutie od návrhu,
- aktuálny postup od historického,
- produkčný proces od testovacieho,
- Core správanie od zákazníckej úpravy,
- pôvodný zdroj od jeho kópie alebo automaticky vytvoreného súhrnu.
Pôvod informácie nie je iba meno autora. Je to sled, ktorý umožňuje zistiť, kde informácia vznikla, ako sa dostala do znalostnej bázy a či bola po ceste upravená.
Napríklad odpoveď AI môže vychádzať zo súhrnu incidentu. Súhrn bol vytvorený z exportu tiketu. V tikete sa nachádzal postup skopírovaný zo správy v internom chate. Pôvodné rozhodnutie však bolo neskôr zmenené v technickej špecifikácii.
Ak sa v znalostnej báze zachoval iba súhrn bez väzby na pôvodné zdroje, nie je možné overiť:
- či súhrn zachoval všetky podmienky,
- či nevynechal výnimku,
- či pôvodná informácia stále platí,
- či existuje novší a autoritatívnejší zdroj.
AI potom môže citovať vetu, ale nevie preukázať, prečo jej máme dôverovať.
Skutočné náklady (čas, chaos, riziko)
Chýbajúce metadáta sa často prejavia až vtedy, keď sa nájdu dve rozdielne odpovede.
Jeden dokument tvrdí, že stav objednávky môže support opraviť manuálne. Druhý prikazuje incident eskalovať. Tretí opisuje automatickú opravu pomocou synchronizácie.
Človek začne zisťovať:
- Ktorý dokument je najnovší?
- Ktorý bol schválený?
- Platí pravidlo pre produkciu?
- Týka sa všetkých zákazníkov?
- Nebol postup po oprave incidentu zrušený?
- Kto môže potvrdiť aktuálny stav?
Ak tieto údaje nie sú zapísané, tím ich hľadá v histórii tiketov, správach, e-mailoch alebo v hlavách seniorov.
Vznikajú tri druhy nákladov.
- Čas
Support a testerka kontrolujú viacero zdrojov a opakovane žiadajú vlastníka funkcionality o potvrdenie. AI síce vyhľadá odpoveď rýchlo, ale človek musí ručne overiť, či ju možno použiť.
- Chaos
Rovnaký postup existuje v niekoľkých dokumentoch. Každá kópia má inú formuláciu a nikde nie je uvedené, ktorá verzia je rozhodujúca.
- Riziko
AI použije pracovnú poznámku ako záväzné pravidlo, historický workaround ako aktuálny postup alebo Custom riešenie ako odporúčanie pre všetkých zákazníkov.
Riziko rastie, ak sa informácie automaticky kopírujú, sumarizujú alebo presúvajú medzi systémami. Pri každej ďalšej kópii môže zmiznúť časť kontextu.
Z pôvodnej vety:
„V testovacom prostredí klienta ABC možno do nasadenia opravy dočasne vypnúť kontrolu platobného stavu.“
môže po skrátení vzniknúť:
„Pri probléme s platbou vypnite kontrolu platobného stavu.“
Text je kratší a zdanlivo použiteľnejší. Zmizlo z neho však prostredie, klient, dočasnosť aj podmienka nasadenia opravy.
Ak AI nevie dohľadať pôvod, nemá sa k čomu vrátiť a chýbajúce podmienky nemá ako overiť.
Minimálny model riešenia
Nie každý zdroj potrebuje desiatky technických polí. Potrebuje však minimálnu identitu, rozsah platnosti, stav a väzbu na pôvod.
Použiteľný model môže vyzerať takto:
| Metadáta | Čo musí byť jasné |
|---|---|
| Identifikátor zdroja | Ktorý konkrétny dokument alebo záznam bol použitý |
| Názov | Čo zdroj opisuje |
| Typ zdroja | Špecifikácia, manuál, incident, tiket, zápis, rozhodnutie alebo súhrn |
| Pôvodné umiestnenie | Kde možno nájsť autoritatívny zdroj |
| Vlastník | Kto zodpovedá za správnosť a aktualizáciu |
| Autor alebo pôvodca | Kto alebo ktorý systém informáciu vytvoril |
| Produkt a modul | Ktorej časti systému sa informácia týka |
| Verzia | Pre ktorú verziu systému platí |
| Prostredie | Produkcia, testovacie, vývojové alebo iné prostredie |
| Rozsah | Core, Custom, konkrétny klient, rola alebo proces |
| Stav | Návrh, schválené, platné, čaká na kontrolu alebo archivované |
| Platnosť | Odkedy a prípadne dokedy sa informácia používa |
| Posledné overenie | Kedy niekto potvrdil súlad so systémom |
| Úroveň dôvery | Či ide o záväzný, podporný alebo neoverený zdroj |
| Nahradenie | Ktorý novší zdroj túto informáciu nahradil |
| Odvodenie | Z akých podkladov vznikol súhrn alebo upravená verzia |
| Prístupové obmedzenie | Kto smie zdroj alebo jeho obsah použiť |
Pri incidente s platbou by záznam mohol obsahovať:
| Pole | Hodnota |
|---|---|
| Typ zdroja | Incident a dočasný workaround |
| Produkt a modul | Objednávky, platobná integrácia |
| Verzia | 3.6 |
| Prostredie | Testovacie |
| Rozsah | Custom, klient ABC |
| Stav | Archivované |
| Platnosť | Do nasadenia opravy chyby PAY-1842 |
| Vlastník | Integračný tím |
| Posledné overenie | 14. 5. 2024 |
| Nahradené zdrojom | Produkčný postup pre spracovanie chybného výsledku platby, verzia 4.1 |
| Úroveň dôvery | Historický zdroj, nepoužívať ako aktuálny návod |
Takto označený incident môže zostať v znalostnej báze. Pomáha pri analýze histórie a pri opakovaní podobného problému. AI ho však nesmie prezentovať ako aktuálny produkčný postup.
Dôležité je určiť aj poradie dôveryhodnosti zdrojov.
Pre konkrétny projekt môže platiť napríklad toto poradie:
- Schválená a aktuálna špecifikácia alebo prevádzkový postup.
- Aktuálny manuál s určeným vlastníkom.
- Schválené rozhodnutie zaznamenané v projektovom nástroji.
- Overený incident alebo support záznam.
- Pracovná poznámka, komentár alebo zápis zo stretnutia.
- Automaticky vytvorený súhrn bez ľudského overenia.
Toto poradie nie je univerzálne. Firma ho musí nastaviť podľa svojho workflow. Podstatné je, aby pri konflikte nevyhral zdroj iba preto, že používa podobnejšie slová alebo bol ľahšie vyhľadateľný.
Ak si zdroje odporujú a metadáta neumožňujú konflikt rozhodnúť, AI nemá vybrať odpoveď odhadom. Má pomenovať neistotu, uviesť konfliktné zdroje a vyžiadať overenie.
Praktická odpoveď môže znieť:
„Našla som dva rozdielne postupy. Incident PAY-1720 povoľuje manuálnu zmenu stavu iba v testovacom prostredí klienta ABC vo verzii 3.6. Aktuálny produkčný postup pre verziu 4.1 vyžaduje eskaláciu integračnému tímu. Pre produkciu preto používam novší schválený postup.“
Takáto odpoveď neukazuje iba výsledok. Ukazuje aj dôvod, prečo bol jeden zdroj uprednostnený.
Pri spracovaní dokumentu na menšie obsahové bloky sa nesmú metadáta stratiť. Každý samostatne vyhľadateľný blok musí zdediť aspoň údaje potrebné na správne použitie:
- identifikátor a názov zdroja,
- typ zdroja,
- verziu a prostredie,
- Core alebo Custom rozsah,
- stav platnosti,
- vlastníka,
- dátum posledného overenia,
- odkaz na pôvodný dokument.
Nestačí, ak sú tieto údaje iba na prvej strane dokumentu a jednotlivé bloky sa do znalostnej bázy uložia bez nich.
Prepojenie na kvalitu a workflow
Metadáta nemajú byť dopĺňané až pri nahrávaní dokumentov do AI nástroja. Vtedy už často nikto nevie spoľahlivo určiť, prečo starý dokument vznikol a či ešte platí.
Musia byť súčasťou životného cyklu dokumentácie.
Pri vytvorení dokumentu sa určia:
- vlastník,
- typ zdroja,
- produkt a modul,
- rozsah platnosti,
- Core alebo Custom charakter,
- stav dokumentu.
Pri schválení sa zaznamená:
- kto obsah overil,
- kedy bol overený,
- pre ktorú verziu a prostredie platí,
- od ktorého dátumu sa má používať.
Pri zmene systému sa skontroluje:
- ktoré zdroje zmena ovplyvňuje,
- ktoré dokumenty treba aktualizovať,
- ktoré staré postupy treba označiť ako nahradené,
- či sa musí znova vytvoriť index alebo obsahové bloky pre AI,
- či sa zmenené informácie zobrazujú s aktuálnymi metadátami.
Pri archivácii sa dokument nemusí vymazať. Musí však byť jasné:
- že už nie je aktuálny,
- dokedy platil,
- čím bol nahradený,
- na aký účel sa ešte môže použiť.
Do Definition of Done možno zaradiť formuláciu:
„Všetky nové alebo zmenené zdroje majú určeného vlastníka, typ, stav, rozsah platnosti, verziu, prostredie, rozlíšenie Core a Custom a dátum posledného overenia. Neaktuálne zdroje sú označené ako nahradené alebo archivované a obsahujú väzbu na aktuálny zdroj. Metadáta sa zachovali aj pri spracovaní dokumentu pre vyhľadávanie pomocou AI.“
Testerka môže kontrolovať nielen obsah odpovede AI, ale aj prácu so zdrojmi.
Praktické testy môžu overiť:
- či AI uprednostní aktuálny schválený dokument pred starým incidentom,
- či nepoužije postup z testovacieho prostredia v produkcii,
- či odlíši Core pravidlo od Custom úpravy,
- či upozorní na neoverený alebo chýbajúci stav zdroja,
- či pri konflikte zdrojov nevymyslí jednoznačnú odpoveď,
- či dokáže uviesť dokument, z ktorého odpoveď pochádza,
- či citácia smeruje na pôvodný zdroj, nie iba na jeho neoverenú kópiu,
- či používateľ nemá prístup k informácii, ktorú podľa svojich oprávnení nemá vidieť.
Prístupové oprávnenia sú súčasťou pôvodu a kontextu zdroja. Ak má AI prístup k internému dokumentu, neznamená to, že jeho obsah môže zobraziť každému používateľovi.
Rovnako dôležitá je spätná dohľadateľnosť. Ak AI poskytne nesprávnu odpoveď, tím musí vedieť zistiť:
- ktoré zdroje boli nájdené,
- ktoré časti boli použité,
- aké metadáta mali,
- prečo bol jeden zdroj uprednostnený,
- či chyba vznikla v dokumentácii, metadátach, vyhľadávaní alebo vo výslednej odpovedi.
Bez tejto stopy sa každá chybná odpoveď rieši ako nový izolovaný problém. S dohľadateľným pôvodom sa môže opraviť konkrétny zdroj alebo pravidlo, ktoré chybu spôsobilo.
Krátke zhrnutie
AI nestačí vedieť, čo sa v zdroji píše. Musí vedieť aj:
- odkiaľ informácia pochádza,
- kto za ňu zodpovedá,
- pre ktorý produkt, modul, klienta a prostredie platí,
- ktorej verzie systému sa týka,
- či ide o Core alebo Custom riešenie,
- či je zdroj schválený, aktuálny alebo archivovaný,
- kedy bol naposledy overený,
- či bol nahradený novším zdrojom,
- z akých podkladov vznikol,
- kto má oprávnenie jeho obsah použiť.
Metadáta nie sú administratívna príloha k dokumentácii. Rozhodujú o tom, či možno nájdenú informáciu bezpečne použiť.
Ak AI dokáže citovať vetu, ale nevie vysvetliť jej pôvod, platnosť a rozsah, ešte nemá spoľahlivý zdroj. Má iba text.