Dobrá dokumentace aplikace nemá být dodatečný popis toho, co už
někdo vytvořil. Ve Flexideu vzniká přímo spolu s aplikací: u datových
struktur, přehledů, filtrů, sloupců, akcí i procesů. Díky tomu není
dokumentace odděleným textem někde vedle systému, ale součástí jeho
definice. Popisuje, proč daná část aplikace existuje, jakou má roli v
provozu a jak se zapojuje do celku.
Důležité je, že strukturovaná dokumentace uprostřed schématu nevzniká jako samostatná ruční práce až dodatečně. Vzniká průběžně a automaticky při běžných životních událostech aplikace: při přesunu XDS definice na server, při uložení nové verze tabulky nebo přehledu, při release akce, při úpravě procesního nastavení či dalších konfiguračních změnách. V těchto okamžicích se z jednotlivých definic extrahují dokumentační informace, vazby, identifikátory a kontext použití. Dokumentace tak není oddělený manuál, který je potřeba ručně udržovat vedle systému, ale průběžně aktualizovaná znalostní vrstva vznikající přímo z toho, jak se aplikace skutečně definuje, mění a provozuje.
Dokumentace jako součást systému
U běžných informačních systémů často vzniká dokumentace až dodatečně. Nejdříve se analyzuje, potom vyvíjí, upravuje, testuje a teprve nakonec se někdo pokouší popsat, co vlastně vzniklo. Výsledkem bývá dokument, který rychle zastarává, protože žije odděleně od samotné aplikace. Flexideo na to jde jinak. Protože aplikace vzniká z definic, je možné dokumentaci vkládat přímo do míst, kde vzniká význam aplikace. Dokumentace tak není jen uživatelský manuál. Je to strukturovaný popis systému, který se postupně skládá ze stejných stavebních částí jako samotná aplikace. Popisují se datové typy, jejich vlastnosti, přehledy, podmínky, filtry, sloupce, řazení, seskupení, nástroje, akce, role, spouštěče, vstupy, výstupy i procesní návaznosti. Každá důležitá část aplikace může nést vlastní vysvětlení svého účelu.
Od XDS k pochopení aplikace
Základem Flexideo aplikace je XDS definice. Ta popisuje datovou strukturu aplikace, tedy to, jaké typy dokumentů v systému existují, jaké mají vlastnosti a jak mezi sebou souvisí. U segmentů XDS je možné používat atribut documentation. Ten slouží k tomu, aby u konkrétní části definice nebyl jen technický popis, ale také lidské vysvětlení jejího významu. Například nestačí vědět, že v systému existuje vlastnost „odběratel“, „stav“, „datum platnosti“ nebo „organizace“. Důležité je vědět, co přesně v dané aplikaci znamená, kdo ji vyplňuje, jak se používá, jak ovlivňuje další výpočty, přehledy, procesy nebo rozhodování. Právě zde začíná strukturovaná dokumentace. Ne v samostatném Wordu, ale přímo u stavebních prvků aplikace.
Dokumentace přehledů
Aplikace však není tvořena pouze datovou strukturou. Uživatelé většinu času nepracují přímo s definicí dat, ale s přehledy, složkami, rozhraními a nástroji. Proto je důležité dokumentovat také samotné přehledy. U nich nestačí popsat, že zobrazují nějaký seznam záznamů. Důležité je vysvětlit: k čemu přehled slouží, pro jakou roli je určen, jaký typ rozhodnutí podporuje, jaká data zobrazuje, podle čeho je filtruje, jak jsou sloupce sestaveny, co znamenají jednotlivé podmínky, jaké řazení nebo seskupení pomáhá uživateli pochopit situaci a jaké nástroje jsou v daném místě k dispozici. Proto mohou nést dokumentaci i jednotlivé části přehledů: podmínky, filtry, sloupce, řazení, seskupení, nástroje a další prvky rozhraní. Tím vzniká mnohem přesnější popis aplikace. Neříká pouze „zde je seznam obchodních případů“, ale vysvětluje, proč je tento seznam sestaven právě takto a jak má být používán v reálné práci.
Dokumentace akcí
Další důležitou vrstvou jsou akce. Akce ve Flexideu představují konkrétní pracovní kroky, které nad daty něco provedou, změní, založí, zkontrolují, odešlou nebo předají dál. U akce je proto vhodné dokumentovat zejména její účel. Tedy proč v aplikaci existuje a jaký problém řeší. Dále je důležité popsat, kdo ji smí nebo má spouštět, v jaké situaci se používá, jaké role se jí účastní, jaké má spouštěče, do jaké fáze procesu patří a jaké má vstupy a výstupy. Dobře zdokumentovaná akce odpovídá na otázky: Co se touto akcí má stát? Kdy ji má uživatel použít? Co musí být před jejím spuštěním splněno? Jaká data akce potřebuje? Co po jejím dokončení vznikne nebo se změní? Jaký další krok na ni navazuje? Taková dokumentace je důležitá nejen pro uživatele, ale i pro implementátory, správce aplikace a budoucí rozvoj systému. Umožňuje pochopit logiku aplikace bez nutnosti složitě zpětně analyzovat chování systému.
Dokumentace procesů
Nejvyšší úroveň dokumentace vzniká u procesů. Proces není jen jedna tabulka, jeden přehled nebo jedna akce. Proces je propojení více částí aplikace do funkčního celku. Právě zde se ukazuje, jak se jednotlivé tabulky, přehledy, akce, podmínky a automatizace zapojují do reálného provozu firmy. Procesní dokumentace by měla popsat, jaký firemní děj systém podporuje, kde začíná, jaké má fáze, jaké role se ho účastní, jaké záznamy se v jeho průběhu vytvářejí, jaké akce se spouštějí, jaké kontroly probíhají, kdy dochází k předání odpovědnosti a kde může nastat eskalace. Tím se dokumentace dostává z úrovně „popisu obrazovek“ na úroveň pochopení fungování firmy.
Strukturovaná dokumentace jako most mezi lidmi a systémem
Cílem strukturované dokumentace není jen pomoci uživateli najít odpověď na otázku, kam má kliknout. Jejím cílem je propojit několik světů najednou. Pomáhá klientovi pochopit, jak je jeho provoz v aplikaci zachycen. Pomáhá implementátorům udržet kontinuitu při rozvoji. Pomáhá vývojářům a správcům systému pochopit důvody, proč byla určitá část navržena právě takto. A do budoucna vytváří základ pro kontextovou nápovědu, AI asistenci a kontrolu změn. V dobře vedené dokumentaci není pouze výsledek. Je v ní zachycen i záměr. To je důležité zejména u systémů, které se v čase vyvíjejí. Firma se mění, procesy se upravují, přibývají nové role, výjimky, napojení a požadavky. Pokud dokumentace žije přímo u definic aplikace, může růst spolu se systémem.
Dokumentace, která se dá použít znovu
Velkou výhodou strukturovaného přístupu je také opakovaná použitelnost. Jakmile jsou jednotlivé části aplikace popsány přímo ve své struktuře, lze z nich vytvářet různé typy výstupů. Z jedné dokumentační vrstvy může vzniknout technická dokumentace, implementační poznámky, uživatelská nápověda, popis procesů, podklad pro školení, kontrolní seznam pro testování nebo kontext pro AI asistenta. Stejný popis tedy nemusí být znovu a znovu ručně přepisován do různých dokumentů. Může být použit podle potřeby v různých podobách.
Role zpětné vazby
Strukturovaná dokumentace není jednorázová aktivita. Je součástí cyklu návrhu, realizace, používání a dalšího rozvoje aplikace. Zpětná vazba z provozu se promítá do návrhu řešení. Návrh se propisuje do XDS definic, serverové vrstvy, složek a rozhraní, přehledů, akcí a procesů. Tyto části se následně dokumentují a jejich popis pomáhá zpětně ověřovat, zda aplikace skutečně odpovídá realitě. Dokumentace tak není konec práce. Je to nástroj, který pomáhá řídit změnu.
Základ pro online nápovědu a AI asistenci
Jakmile je dokumentace strukturovaná, může se stát základem pro moderní nápovědu přímo v aplikaci. Uživatel by se nemusel proklikávat dlouhým manuálem. Mohl by se ptát přímo v kontextu obrazovky, přehledu, akce nebo procesu, ve kterém právě pracuje. Systém by mu mohl odpovědět na základě dokumentace konkrétní části aplikace. Například: Co znamená tento sloupec? Proč tu tento záznam nevidím? Kdy mám použít tuto akci? Co se stane po jejím spuštění? Kdo má řešit další krok? Proč je tento stav blokovaný? Jaký proces na tuto obrazovku navazuje? Aby taková nápověda fungovala dobře, nestačí obecný manuál. Je potřeba přesná, strukturovaná a kontextová dokumentace přímo u prvků aplikace.
Dlouhodobá hodnota aplikace
Flexideo aplikace často řeší klíčové provozní agendy firmy. Takový systém nemá být jen sada obrazovek a databázových tabulek. Má být dlouhodobě srozumitelným aktivem firmy. Strukturovaná dokumentace k tomu významně přispívá. Pomáhá udržet znalost o systému i ve chvíli, kdy se mění lidé, role, procesy nebo požadavky. Snižuje závislost na paměti jednotlivců. Urychluje změny. Zpřehledňuje podporu. Zlepšuje předávání know-how. A vytváří pevný základ pro další rozvoj. Dobře zdokumentovaná aplikace není jen lépe popsaná. Je lépe pochopitelná, lépe udržovatelná a lépe připravená na budoucnost.
Shrnutí
Strukturovaná dokumentace aplikací ve Flexideu vzniká přímo u definic, přehledů, akcí a procesů. Nejde o dodatečný text mimo systém, ale o součást samotné aplikace. Díky tomu lze dokumentovat nejen to, jak aplikace vypadá, ale hlavně proč tak funguje. Od XDS segmentů přes přehledy a akce až po procesní automatizaci vzniká vrstva znalostí, která propojuje technickou definici systému s reálným fungováním firmy. Taková dokumentace je základem pro kvalitní implementaci, dlouhodobou údržbu, uživatelskou nápovědu, AI asistenci i další rozvoj aplikace.
