Séria: Ako písať dokumentáciu a manuály v IT projekte
Reálny problém z praxe
Používateľ nahlásil, že po odoslaní objednávky nedostal potvrdzovací e-mail.
V znalostnej báze sme našli tri dokumenty:
- „Odosielanie e-mailov“
- „Notifikácie objednávok“
- „Riešenie problémov s objednávkami“
Prvý dokument opisoval nastavenie e-mailového servera. Druhý obsahoval zoznam udalostí, pri ktorých systém posiela notifikácie. Tretí bol zmesou starých incidentov, poznámok zo supportu a dočasných riešení.
Človek musel otvoriť všetky tri dokumenty a postupne zisťovať:
- či sa e-mail odosiela pri vytvorení alebo až pri potvrdení objednávky,
- či je notifikácia súčasťou základnej funkcionality alebo zákazníckej úpravy,
- kde skontrolovať stav odoslania,
- ktoré riešenie je stále platné,
- či problém patrí vývoju, administrátorovi alebo supportu.
AI asistent pracujúci s rovnakou znalostnou bázou mal podobný problém. Na otázku používateľa našiel viacero obsahovo príbuzných častí, ale nevedel spoľahlivo určiť, ktorá z nich opisuje aktuálny stav systému.
Odpovedal preto všeobecne:
„Skontrolujte nastavenie e-mailového servera a konfiguráciu notifikácií.“
Odpoveď nebola úplne nesprávna. Nebola však použiteľná. Chýbal jej konkrétny postup, podmienky platnosti aj rozlíšenie medzi bežným správaním systému a zákazníckou konfiguráciou.
Dokumentácia obsahovala potrebné informácie, ale nebola pripravená na to, aby sa podľa nej dalo spoľahlivo pracovať.
Čo sa tu vlastne pokazilo (analýza systému)
Problém nebol v tom, že by dokumentácia bola príliš krátka. Problémom nebol ani nedostatok odborných informácií.
Chýbala jej jednotná štruktúra.
Každý dokument vznikol v inom čase, na iný účel a podľa inej logiky:
- vývojár opísal technické nastavenie,
- analytik zaznamenal funkčné pravidlá,
- testerka doplnila overovacie kroky,
- support pridal riešenia konkrétnych incidentov,
- administrátor zapísal zmenu konfigurácie.
Jednotlivé informácie boli správne, ale nebolo jasné, ako spolu súvisia.
Človek dokáže neúplnú štruktúru čiastočne nahradiť skúsenosťou. Pozná názvy komponentov, pamätá si starší incident alebo sa opýta kolegu. Aj preto môže neprehľadná dokumentácia vo firme roky pôsobiť ako dostatočná.
AI túto skúsenosť nemá. Pracuje s obsahom, ktorý dostane. Ak dokument neobsahuje kontext, AI si ho nemôže bezpečne domyslieť. Ak existujú dve protichodné informácie bez označenia platnosti, nevie spoľahlivo rozhodnúť, ktorá je aktuálna.
Rovnaké nedostatky však komplikujú prácu aj človeku:
- nejasný názov sťažuje vyhľadanie dokumentu,
- dlhý súvislý text spomaľuje orientáciu,
- chýbajúci účel nehovorí, na aký problém je dokument určený,
- chýbajúce podmienky platnosti vedú k použitiu nesprávneho postupu,
- neoznačená zákaznícka úprava sa môže zameniť za štandardné správanie,
- zastaraný postup môže vyzerať rovnako dôveryhodne ako aktuálny,
- neurčený vlastník znamená, že nikto nezodpovedá za aktualizáciu.
Dokumentácia pripravená pre AI preto nie je osobitný typ dokumentácie. Je to dokumentácia, v ktorej sú vzťahy, význam a hranice platnosti zapísané priamo, namiesto toho, aby zostali iba v hlavách skúsených ľudí.
Skutočné náklady (čas, chaos, riziko)
Zlá štruktúra sa zvyčajne neprejaví ako jedna veľká chyba. Náklady vznikajú postupne pri každom hľadaní, overovaní a vysvetľovaní.
Pri opísanom probléme môže jeden pracovník supportu stráviť pätnásť minút hľadaním správneho postupu. Ak si nie je istý, kontaktuje seniora. Senior otvorí tie isté dokumenty, porovná ich s aktuálnou konfiguráciou a vysvetlí, ktorý postup ešte platí.
Pri jednom incidente ide možno o polhodinu. Pri desiatkach podobných požiadaviek mesačne už vznikajú hodiny práce, ktoré sa v projektových výkazoch často neobjavia ako problém dokumentácie.
Dopad má viacero podôb:
- Čas
Ľudia čítajú celé dokumenty, pretože nevedia, v ktorej časti je odpoveď. Rovnaké informácie si opakovane overujú u seniorov.
- Chaos
Každý člen tímu používa iný dokument alebo vlastnú poznámku. V obehu zostávajú viaceré verzie toho istého postupu.
- Riziko
Support odporučí riešenie určené pre iného zákazníka. Administrátor zmení konfiguráciu bez poznania dopadu. Testerka vyhodnotí očakávané správanie ako chybu alebo skutočnú chybu uzavrie ako konfiguráciu.
- Závislosť od konkrétnych ľudí
Dokumentácia funguje iba vtedy, keď je dostupný človek, ktorý vysvetlí jej kontext.
- Nespoľahlivé odpovede AI
AI nájde správne vety, ale spojí ich s nesprávnou verziou systému, rolou používateľa alebo zákazníckou konfiguráciou.
Nasadenie AI nad takouto dokumentáciou problém nevyrieši. Iba ho zviditeľní. Ak sa nedá podľa dokumentácie pracovať bez telefonátu seniorovi, nebude podľa nej spoľahlivo pracovať ani AI.
Minimálny model riešenia
Cieľom nie je prepísať všetky dokumenty do formátu vhodného iba pre stroj. Dokumentácia musí zostať čitateľná pre ľudí a zároveň dostatočne jednoznačná na vyhľadávanie a spracovanie pomocou AI.
Minimálny použiteľný model môže mať sedem častí.
1. Jednoznačný názov
Názov má pomenovať konkrétny obsah, nie všeobecnú oblasť.
Slabý názov:
„E-maily“
Použiteľný názov:
„Objednávka zostala bez potvrdzovacieho e-mailu po zmene stavu na Potvrdená“
Človek už z názvu rozpozná situáciu. AI získa presnejší podklad na vyhľadanie relevantného dokumentu.
2. Účel dokumentu
Na začiatku má byť krátko uvedené:
- aký problém dokument rieši,
- pre koho je určený,
- čo podľa neho možno vykonať alebo overiť.
Príklad:
„Postup je určený pre pracovníka supportu, ktorý rieši chýbajúci potvrdzovací e-mail po potvrdení objednávky. Slúži na základnú diagnostiku pred eskaláciou na administrátora alebo vývoj.“
Takáto veta určuje hranice dokumentu. Znižuje riziko, že človek alebo AI použije postup v nesprávnej situácii.
3. Kontext a podmienky platnosti
Dokument má uviesť, pre akú časť systému a za akých podmienok platí.
Napríklad:
- produkt alebo modul,
- verzia systému,
- prostredie,
- používateľská rola,
- Core alebo Custom,
- konkrétny zákazník, ak ide o zákaznícku úpravu,
- dátum posledného overenia.
Bez týchto údajov môže byť aj technicky správny postup použitý nesprávne.
4. Očakávaný stav
Dokumentácia nemá opisovať iba kroky. Musí vysvetliť, čo sa má stať.
V tomto prípade:
„Potvrdzovací e-mail sa vytvorí po zmene objednávky zo stavu Nová na stav Potvrdená. Samotné uloženie rozpracovanej objednávky e-mail nevytvorí.“
Táto informácia pomáha človeku rozlíšiť chybu od očakávaného správania. AI vďaka nej nemusí odvodiť pravidlo z jednotlivých krokov.
5. Diagnostický alebo pracovný postup
Postup má byť rozdelený na krátke, jednoznačné kroky. Jeden krok má obsahovať jednu činnosť a očakávaný výsledok.
Napríklad:
- Otvor detail objednávky.
- Skontroluj aktuálny stav objednávky.
- Ak objednávka nie je v stave Potvrdená, nejde o chybu odoslania e-mailu.
- Ak je objednávka v stave Potvrdená, skontroluj záznam v histórii notifikácií.
- Ak záznam neexistuje, eskaluj problém na aplikačný support.
- Ak záznam existuje so stavom Chyba, prilož chybový kód a eskaluj problém administrátorovi.
- Ak je záznam v stave Odoslané, over cieľovú adresu a informuj používateľa o kontrole nevyžiadanej pošty.
Takýto postup neskrýva rozhodovanie v dlhom odseku. Človek aj AI dokážu rozpoznať podmienku, vykonať správny krok a určiť ďalšiu zodpovednú rolu.
6. Výnimky, obmedzenia a súvisiace dokumenty
Výnimky nesmú zostať ukryté v poznámke na konci dokumentu.
Ak zákazník používa vlastnú šablónu, externú e-mailovú službu alebo odlišný stavový model, musí to byť označené ako Custom.
Súvisiace dokumenty majú byť uvedené spolu s vysvetlením, prečo ich má človek otvoriť.
Nestačí uviesť:
- „Konfigurácia e-mailov“
- „Zoznam notifikácií“
Lepšie je uviesť:
- „Konfigurácia e-mailového servera“ použite pri chybe spojenia alebo autentifikácie.
- „Prehľad udalostí objednávky“ použite na overenie, ktorý stav spúšťa konkrétnu notifikáciu.
Človek tak nemusí hádať význam odkazu. AI dostáva informáciu o vzťahu medzi dokumentmi.
7. Vlastník a životný cyklus
Každý dokument má mať určeného vlastníka a stav.
Minimálne údaje sú:
- vlastník obsahu,
- dátum poslednej kontroly,
- stav dokumentu,
- verzia alebo obdobie platnosti.
Stav môže byť napríklad:
- návrh,
- platný,
- čaká na aktualizáciu,
- archivovaný.
Dokument bez vlastníka môže zostať formálne dostupný, ale nikto nezodpovedá za jeho správnosť. AI potom môže nájsť starý obsah rovnako ľahko ako aktuálny.
Mini checklist jednej dokumentačnej položky
Pred zverejnením stačí overiť:
- Je z názvu jasné, aký problém alebo proces dokument opisuje?
- Je uvedené, komu je dokument určený?
- Je jasné, kedy sa má a nemá použiť?
- Obsahuje očakávaný výsledok?
- Sú kroky krátke a jednoznačné?
- Sú oddelené Core a Custom informácie?
- Sú výnimky označené priamo pri pravidle, ktorého sa týkajú?
- Majú súvisiace dokumenty vysvetlený účel?
- Je uvedený vlastník, stav a dátum poslednej kontroly?
- Dokáže nový člen tímu podľa dokumentu postupovať bez telefonátu seniorovi?
Ak odpoveď na poslednú otázku znie nie, dokument ešte nie je pripravený ani pre človeka, ani pre AI.
Prepojenie na kvalitu a workflow
Dobrá štruktúra nevznikne dodatočným upratovaním raz za rok. Musí byť súčasťou bežného workflow projektu.
Pri zmene funkcionality by tím nemal kontrolovať iba kód a testy. Mal by skontrolovať aj dokumentáciu, ktorú zmena ovplyvňuje.
Ak sa napríklad zmení okamih odoslania potvrdzovacieho e-mailu, aktualizáciu môžu potrebovať:
- funkčná špecifikácia,
- používateľský manuál,
- support postup,
- administrátorská konfigurácia,
- zoznam udalostí a notifikácií,
- znalostná báza používaná AI asistentom.
Nestačí upraviť jeden dokument a predpokladať, že ostatné informácie sa zosúladia samy.
Do Definition of Done možno zaradiť konkrétnu formuláciu:
„Boli identifikované a aktualizované všetky dokumenty ovplyvnené zmenou. Dokumentácia obsahuje účel, podmienky platnosti, očakávaný stav, jednoznačný postup, výnimky, rozlíšenie Core a Custom a dátum posledného overenia. Neaktuálne informácie boli označené alebo archivované.“
Testerka môže pri overovaní zmeny kontrolovať nielen to, či systém funguje podľa zadania, ale aj to, či dokumentácia opisuje skutočné správanie.
Praktická kontrola môže zahŕňať tieto otázky:
- Zodpovedá postup aktuálnej verzii systému?
- Je očakávaný výsledok zhodný s testami?
- Sú chybové stavy a obmedzenia uvedené priamo?
- Je zákaznícka výnimka jasne oddelená od základnej funkcionality?
- Vie support podľa dokumentu určiť, kedy má problém eskalovať?
- Dostane AI pri vyhľadaní dokumentu dostatok kontextu na bezpečnú odpoveď?
Takto sa dokumentácia stáva kontrolným mechanizmom kvality. Pomáha odhaliť nejasnosti v požiadavkách, rozdiely medzi Core a Custom riešením aj situácie, v ktorých systém síce technicky funguje, ale tím nevie jednoznačne vysvetliť jeho správanie.
AI pripravenosť potom nie je samostatný projekt na konci. Je výsledkom toho, že dokumentácia má vlastníka, jednotnú štruktúru, jasné hranice platnosti a je aktualizovaná spolu so systémom.
Krátke zhrnutie
Dokumentácia pre človeka a dokumentácia pre AI nemajú byť dve oddelené verzie toho istého obsahu.
Obe potrebujú:
- jednoznačný názov,
- jasný účel,
- kontext a podmienky platnosti,
- očakávaný stav,
- krátky a rozhodovateľný postup,
- označené výnimky,
- rozlíšenie Core a Custom,
- vlastníka a dátum kontroly.
Človeku táto štruktúra zrýchľuje orientáciu a znižuje závislosť od seniorov. AI pomáha vybrať správny zdroj, zachovať kontext a neprezentovať zastaranú alebo zákaznícku informáciu ako všeobecné pravidlo.
Ak sa systém zmení, musí sa zmeniť aj dokumentácia. A ak sa podľa nej nedá pracovať bez dodatočného vysvetlenia, ešte nie je pripravená ani pre človeka, ani pre AI.