Schéma architektury na stránce SharePointu bylo vytvořeno v roce 2009. Tehdy bylo přesné, odráželo systém tak, jak existoval v době velké migrace platformy. Nakreslil ho architekt, který strávil tři týdny dokumentováním každé komponenty a jejích vztahů. Od roku 2009 systém obdržel přibližně 4 800 commitů, přispělo k němu patnáct týmů, čtyři komponenty zobrazené na diagramu již neexistují, bylo přidáno jedenáct nových komponent, které nikdy nebyly nakresleny do diagramu, a architekt, který jej nakreslil, odešel do důchodu v roce 2016. Diagram stále existuje. Když se připojí nový vývojář a zeptá se: „Jak systém funguje?“, někdo mu pošle odkaz na SharePoint. Diagram není dokumentace. Je to archeologie.
Dokumentační dluh je technický dluh aplikovaný na vrstvu dokumentace: nahromaděná mezera mezi tím, co dokumentace říká o systému, a tím, co systém skutečně dělá. Architektonický drift, kdy se diagramy oddělují od systémů, které zobrazují, je nejběžnější a nejnebezpečnější formou dokumentačního dluhu. Je nejnebezpečnější, protože vyvolává falešnou důvěru: diagram, který existuje a vypadá profesionálně, dává zúčastněným stranám dojem, že systému rozumí, i když to, co ve skutečnosti vidí, je historický artefakt, který popisuje systém, jenž již v zobrazené podobě neexistuje. Zastaralé diagramy jsou horší než žádné diagramy, protože žádné diagramy lidi nevedou k tomu, aby zjistili, co systém skutečně existuje; zastaralé diagramy lidi vedou k jednání na základě toho, co již není pravda.
Dokumentace bez námahy
SMART TS XL vytváří protokol změn všech úprav programu, závislostí a sady textových zápisníků od předchozího spuštění analýzy.
ZJISTĚTE VÍCE…Pět mechanismů, které způsobují, že diagramy zastarají
V každém článku o driftu dokumentace se píše, že „diagramy časem zastarávají“. Téměř žádný z nich nevysvětluje konkrétní mechanismy, kterými k tomu dochází. Pochopení mechanismů je nezbytné k jejich prevenci, protože různé mechanismy vyžadují různé preventivní strategie.
1. Problém s akumulujícími se deltami. Diagram je snímek systému v určitém časovém bodě. Každá změna kódu po tomto snímku představuje deltu mezi diagramem a realitou. Jednotlivé delty jsou obvykle malé, nová služba, přejmenovaná komponenta, přidaná závislost. Každou z nich lze snadno dokumentovat samostatně. Problém je v tom, že je nikdo nedokumentuje postupně, protože aktualizace diagramu pro každou změnu je vnímána jako režie bez okamžitého přínosu. Po 100 nezaznamenaných deltách je diagram materiálně chybný. Po 1 000 je v podstatě fiktivní.
2. Problém chybějícího původu. Diagram, který nemá žádné programové propojení s kódem, který zobrazuje, nemá žádný mechanismus pro detekci, kdy se stane nepřesným. Neexistuje žádný signál, který by se spustil, když změna v kódové základně odporuje tvrzení v diagramu. Diagram a kód jsou od sebe oddělené artefakty, které popisují stejný systém, ale toto propojení existuje pouze v myslích lidí, kteří diagram nakreslili, a pouze tak dlouho, dokud si ho tito lidé pamatují.
3. Problém s driftem vlastnictví. Architektonické diagramy obvykle vytváří konkrétní osoba v určitém okamžiku. Když tato osoba odejde, odejde s ní i tichá znalost, která diagram učinila přesným, tedy pochopení toho, které komponenty byly záměrně vynechány, které vztahy byly zjednodušeny a které popisky byly zkratkou pro něco složitějšího. Nový správce diagramu zdědí artefakt, který nevytvořil, kterému nemusí plně rozumět a nemá žádnou motivaci ho udržovat na kódové základně, kterou nenavrhl.
4. Problém s rozpadem kvůli nadměrné přesnosti. Diagramy, které zobrazují příliš mnoho detailů, zastarávají rychleji než diagramy, které zobrazují vhodnou abstrakci. Diagram, který zobrazuje každou mikroslužbu, každý koncový bod API a každou databázovou tabulku, je třeba aktualizovat pro každé nasazení. Diagram, který zobrazuje domény služeb a jejich primární vzorce interakce, je třeba aktualizovat pouze při změně hranic domén. Příliš přesné diagramy mají poločas zastaralosti měřený ve sprintech; diagramy s vhodnou abstrakcí mají poločas zastaralosti měřený ve čtvrtletích.
5. Problém s uzamčením formátu. Diagramy uložené jako soubory Visio, snímky PowerPointu, exporty PNG nebo přílohy PDF nelze programově generovat, validovat ani porovnávat. Neexistuje způsob, jak se zeptat: „Odpovídá tento diagram stále kódu?“, protože diagram je pixelový obrázek a kód je text. Volba formátu provedená při vytváření diagramu určuje, zda lze diagram někdy validovat vůči systému, který zobrazuje.
Katastrofa dokumentace staršího systému
U moderních cloudových systémů s aktivními vývojovými týmy je zastaralost diagramů problémem managementu, který se řeší pomocí postupů „architektura jako kód“, nástrojů pro živou dokumentaci a inženýrské disciplíny. Systém se často mění; diagram lze aktualizovat tak, aby odpovídal, pokud je proces správný.
U starších systémů je problém odlišný v druhu, nejen v rozsahu.
Schéma architektury nakreslené během revize návrhu mainframe systému v roce 1992 mohlo od svého vzniku nashromáždit 30 let změn kódu. Každý rok aktivní údržby komplexního portfolia COBOL produkuje stovky commitů, přidání nových programů, vyřazení starých programů, aktualizaci sešitů a reorganizaci toků úloh JCL. Diagram z roku 1992 byl tehdy přesný. Od té doby je jeho přesnost postupně klesá. Do roku 2026 může být rozdíl mezi diagramem a systémem větší než samotný původní systém, existuje více nových programů, které v diagramu nejsou, než programů z původního systému, které stále běží tak, jak byly původně navrženy.
To, co to činí katastrofálním, nikoli pouze nepohodlným, je způsob, jakým je diagram používán. Když modernizační tým dorazí, aby systém posoudil, neví, že je diagram chybný. Nemají jak zjistit, jak moc chybný je. Diagram vypadá profesionálně. Má rámečky s komponentami, šipky vztahů, anotace. Naznačuje, že někdo tomuto systému rozuměl natolik dobře, že ho nakreslil. Tým jej používá jako výchozí bod a každá analýza postavená na špatném výchozím bodu vede k chybným závěrům.
Rámec auditu Docuwriter to jasně říká: řádný audit dokumentace „proměňuje neurčité obavy v ověřitelná fakta“. U starších systémů audit dokumentace téměř vždy přináší stejné zjištění: diagramy buď chybí, nebo jsou tak staré, že představují systém, který již léta neexistuje. Ověřitelná fakta, když se konečně objeví, popisují systém podstatně odlišný od toho, se kterým kdokoli pracoval.
Specifický způsob selhání: modernizační tým odhaduje rozsah migrace z diagramu z roku 1992. Ten ukazuje 180 komponent. Strukturální analýza skutečné kódové základny odhaluje 340 programů, z nichž 80 je mrtvý kód a dalších 40 bylo přidáno po roce 1992 a nikdy nebyly znázorněny na diagramu. Odhad rozsahu byl před napsáním prvního řádku nového kódu dvojnásobně chybný.
Kategorie diagramů podle míry zastaralosti
Ne všechny diagramy zastarávají stejnou rychlostí. Míra zastaralosti závisí na tom, co diagram zobrazuje, jak často se zobrazené prvky mění a jak přesně diagram tyto prvky reprezentuje.
| Typ diagramu | Co se často mění | Míra zastaralosti | Priorita zmírňování |
|---|---|---|---|
| Inventář služeb/komponent | Přidány nové služby, staré služby zrušeny | Vysoký | Kritická – nejvyšší frekvence změn |
| Mapa závislostí/integrace | Přidána API, změněny integrace, upraveny datové toky | Vysoký | Kritické – každé nasazení to může změnit |
| Datový model / ERD | Změny schématu, nové tabulky, úpravy sloupců | Středně vysoký | Vysoká — změny schématu jsou v aktivním vývoji časté |
| Sekvenční diagramy | Změny obchodní logiky, aktualizace API smluv | Střední | Vysoká – jakákoli změna pracovního postupu tyto |
| Infrastruktura / nasazení | Infra-as-code pohání časté změny | Vysoký | Střední – nástroje IaC je mohou automaticky generovat |
| Doména / ohraničený kontext | Organizační a vlastnické změny | Nízký-střední | Nízká – hranice domén se mění čtvrtletně nebo méně |
| Záznamy o rozhodnutích (ADR) | Zřídka se mění (rozhodnutí jsou historická) | Velmi nízký | Nízká – po správném zaznamenání zůstává přesná |
| Graf volání programu (COBOL) | Každá změna kódu to potenciálně změní | Velmi vysoko | Kritické pro starší prvky – změny se neviditelně mění |
| Sešit / schéma (COBOL) | Každá změna FD ovlivňuje více programů | Vysoký | Kritické pro starší verze – změny se nenápadně kaskádovitě mění |
Spodní dva řádky obsahují položky specifické pro starší verze, kterými se nezabývá žádná standardní dokumentace. Graf volání programu v COBOLu je potenciálně zneplatněn každou změnou kódu libovolného programu ve stromu volání. Diagram sdílený 200 programy je zneplatněn pro každý program při změně diagramu. Tyto diagramy mají nejvyšší míru zastaralosti v jakémkoli podnikovém portfoliu a nejzávažnější důsledky, když jsou zastaralé, protože programy, které popisují, jsou ty, které spouštějí nejdůležitější obchodní procesy.
Řešení původu: Sledování diagramů k jejich zdroji
Hlavní příčinou dokumentačního dluhu není absence procesu aktualizace dokumentace. Je to absence původu, sledovatelného odkazu mezi prvkem diagramu a artefaktem kódu, který zobrazuje. Bez původu neexistuje mechanismus pro detekci zastaralosti. S původem je detekce zastaralosti automatická: pokud se artefakt kódu od vygenerování diagramu změnil, diagram je zastaralý.
Původ v dokumentaci existuje na dvou úrovních:
Statický původ je dokumentace generovaná z kódu v určitém časovém bodě s časovým razítkem generování a odkazem na stav kódu (hash commitu, verze, datum analýzy), který dokumentace odráží. Statický původ nezabraňuje zastaralosti, ale umožňuje její detekci: časové razítko ukazuje, že dokumentace byla generována z commitu. abc123 k určitému datu a aktuální commit je def456 k pozdějšímu datu. Mezera mezi těmito dvěma commity je mezera mezi dokumentací a aktuálním kódem.
Dynamický původ je dokumentace generovaná průběžně z kódu, regenerovaná při každé relevantní změně kódu. Dokumentace je vždy aktuální, protože je vždy odvozena z aktuálního stavu kódu. Jedná se o model živé dokumentace, nikoli o diagramy, které si někdo aktualizuje, když si na to vzpomene, ale o diagramy, které se regenerují z kódu vždy, když se kód změní.
Praktický rozdíl pro starší portfolio COBOL: statický přístup k provenienci generuje diagram závislostí z aktuální analýzy zdrojového kódu COBOL a opatří jej časovým razítkem. Každý týden lze analýzu znovu spustit a nový diagram porovnat s předchozím. Změny jsou viditelné jako rozdíly mezi po sobě jdoucími výstupy analýzy. Dynamický přístup k provenienci integruje analýzu do procesu správy změn sálového počítače a generuje aktualizovaný diagram vždy, když je program povýšen do produkčního prostředí.
Diagramy jako kód: Co funguje a co mu chybí
Moderní reakcí na zastaralé statické diagramy jsou diagramy jako kód, které vyjadřují architektonickou dokumentaci v textovém formátu, který lze verzovat, porovnávat, kontrolovat a generovat programově. Primárními nástroji jsou Mermaid, PlantUML a model C4 v kódové podobě.
For modern cloud-native systems, diagrams-as-code solves several of the staleness mechanisms: #mermaid-rlk-r1 { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 .edge-animation-slow { stroke-dashoffset: 900; animation: 50s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .edge-animation-fast { stroke-dashoffset: 900; animation: 20s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .error-icon { fill: rgb(204, 120, 92); } #mermaid-rlk-r1 .error-text { fill: rgb(51, 135, 163); stroke: rgb(51, 135, 163); } #mermaid-rlk-r1 .edge-thickness-normal { stroke-width: 1px; } #mermaid-rlk-r1 .edge-thickness-thick { stroke-width: 3.5px; } #mermaid-rlk-r1 .edge-pattern-solid { stroke-dasharray: 0; } #mermaid-rlk-r1 .edge-thickness-invisible { stroke-width: 0; fill: none; } #mermaid-rlk-r1 .edge-pattern-dashed { stroke-dasharray: 3; } #mermaid-rlk-r1 .edge-pattern-dotted { stroke-dasharray: 2; } #mermaid-rlk-r1 .marker { fill: rgb(145, 145, 141); stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 .marker.cross { stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 svg { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; } #mermaid-rlk-r1 p { margin: 0px; } #mermaid-rlk-r1 .label { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; color: rgb(25, 25, 25); } #mermaid-rlk-r1 .cluster-label text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span p { background-color: transparent; } #mermaid-rlk-r1 .label text, #mermaid-rlk-r1 span { fill: rgb(25, 25, 25); color: rgb(25, 25, 25); } #mermaid-rlk-r1 .node rect, #mermaid-rlk-r1 .node circle, #mermaid-rlk-r1 .node ellipse, #mermaid-rlk-r1 .node polygon, #mermaid-rlk-r1 .node path { fill: rgb(240, 240, 235); stroke: rgb(217, 216, 213); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label text, #mermaid-rlk-r1 .node .label text, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-anchor: middle; } #mermaid-rlk-r1 .node .katex path { fill: rgb(0, 0, 0); stroke: rgb(0, 0, 0); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label, #mermaid-rlk-r1 .node .label, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-align: center; } #mermaid-rlk-r1 .node.clickable { cursor: pointer; } #mermaid-rlk-r1 .root .anchor path { stroke-width: 0; stroke: rgb(145, 145, 141); fill: rgb(145, 145, 141) !important; } #mermaid-rlk-r1 .arrowheadPath { fill: rgb(11, 11, 11); } #mermaid-rlk-r1 .edgePaths .path { stroke: rgb(145, 145, 141); stroke-width: 1px; } #mermaid-rlk-r1 .flowchart-link { stroke: rgb(145, 145, 141); fill: none; } #mermaid-rlk-r1 .edgeLabel { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .edgeLabel p { background-color: rgb(245, 230, 216); } #mermaid-rlk-r1 .edgeLabel rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .labelBkg { background-color: rgba(245, 230, 216, 0.5); } #mermaid-rlk-r1 .cluster rect { fill: rgb(204, 120, 92); stroke: rgb(138, 115, 107); stroke-width: 1px; } #mermaid-rlk-r1 .cluster text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .node .collapsed-indicator { fill: rgb(138, 115, 107); stroke: none; opacity: 0.6; } #mermaid-rlk-r1 .node .collapsed-separator { stroke: rgb(138, 115, 107); stroke-width: 0.75px; } #mermaid-rlk-r1 div.mermaidTooltip { position: absolute; text-align: center; max-width: 200px; padding: 2px; font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 12px; background: rgb(204, 120, 92); border: 1px solid rgb(138, 115, 107); border-radius: 2px; pointer-events: none; z-index: 100; } #mermaid-rlk-r1 .flowchartTitleText { text-anchor: middle; font-size: 18px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 rect.text { fill: none; stroke-width: 0; } #mermaid-rlk-r1 .icon-shape, #mermaid-rlk-r1 .image-shape { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .icon-shape p, #mermaid-rlk-r1 .image-shape p { background-color: rgb(245, 230, 216); padding: 2px; } #mermaid-rlk-r1 .icon-shape .label rect, #mermaid-rlk-r1 .image-shape .label rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .label-icon { display: inline-block; height: 1em; overflow: visible; vertical-align: -0.125em; } #mermaid-rlk-r1 .node .label-icon path { fill: currentcolor; stroke: revert; stroke-width: revert; } #mermaid-rlk-r1 .node .neo-node { stroke: rgb(217, 216, 213); } #mermaid-rlk-r1 [data-look=”neo”].node rect, #mermaid-rlk-r1 [data-look=”neo”].cluster rect, #mermaid-rlk-r1 [data-look=”neo”].node polygon { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].swimlane.cluster rect { filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node path { stroke: url(“#mermaid-rlk-r1-gradient”); stroke-width: 1px; } #mermaid-rlk-r1 [data-look=”neo”].node .outer-path { filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node .neo-line path { stroke: rgb(217, 216, 213); filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node circle { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node circle .state-start { fill: rgb(0, 0, 0); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon { fill: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon-neo path { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 :root { –mermaid-font-family: system-ui,”Segoe UI”,Roboto,Helvetica,Arial,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,”Kohinoor Devanagari”,”Kohinoor Bangla”,”Kohinoor Telugu”,”Tamil Sangam MN”,”Kohinoor Gujarati”,”Malayalam Sangam MN”,”Nirmala UI”,”Noto Sans Devanagari UI”,”Noto Sans Devanagari”,”Noto Sans Bengali UI”,”Noto Sans Bengali”,”Noto Sans Telugu UI”,”Noto Sans Telugu”,”Noto Sans Tamil UI”,”Noto Sans Tamil”,”Noto Sans Gujarati UI”,”Noto Sans Gujarati”,”Noto Sans Kannada UI”,”Noto Sans Kannada”,”Noto Sans Malayalam UI”,”Noto Sans Malayalam”,Thonburi,”Leelawadee UI”,”Noto Sans Thai UI”,”Noto Sans Thai”,Kefa,Ebrima,”Noto Sans Ethiopic”,”Abyssinica SIL”,sans-serif,ui-sans-serif,system-ui,-apple-system,”Segoe UI”,Roboto,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,sans-serif; }API GatewayAuth ServiceOrder ServiceOrder DBNotification ServiceUser DB
Tento diagram mořské panny se nachází v repozitáři spolu s kódem, který zobrazuje. Když vývojář přidá novou službu, aktualizuje tento soubor ve stejném pull requestu. Revize kódu zahrnuje změnu diagramu. Dokumentace a kód cestují společně.
Co diagramy jako kód neřeší:
Neřeší dokumentaci starších systémů. Program v COBOLu přidaný do knihovny mainframe vývojářem, který odešle kompilační JCL soubor namísto požadavku na změnu v Gitu, nespustí aktualizaci souboru Mermaid. Proces správy změn v mainframe a proces dokumentace založený na Gitu jsou oddělené systémy bez automatické synchronizace.
Neřeší to problém s nadměrnou přesností. Diagram mořské panny, který je nutné ručně aktualizovat pro každou novou službu, stále vyžaduje lidskou disciplínu, kterou měl tento proces nahradit. Pokud je aktualizace diagramu ručním krokem, bude přeskočena.
Neopravuje zpětně starší diagramy. Pro portfolio COBOL bez existující strojově čitelné dokumentace poskytuje diagramy jako kód rámec pro budoucí dokumentaci, ale nevytváří aktuální dokumentaci.
Přístup ke strukturální analýze pro starší systémy
U starších systémů, kde je používání diagramů jako kódu nepraktické, protože vývojový pracovní postup neprochází Gitem, protože stávající dokumentace je příliš zastaralá na to, aby mohla být výchozím bodem pro textový přístup, nebo protože kódová základna nebyla nikdy formálně zdokumentována, je strukturální analýza kódu jediným mechanismem, který od začátku vytváří aktuální a přesnou dokumentaci.
Strukturální analýza analyzuje skutečný kód, programy v COBOLu, toky úloh JCL, sešity, vložený SQL a odvozuje vztahy závislostí, inventáře programů a datové struktury přímo z obsahu kódu. Výstupem není diagram nakreslený člověkem, který kódu rozuměl; je to diagram algoritmicky odvozený ze samotného kódu. Jeho přesnost je omezena přesností analýzy, nikoli pamětí vývojáře, který jej nakreslil.
Pracovní postup:
praštit
# Structural analysis pipeline for COBOL documentation
# Step 1: Parse all COBOL source in the portfolio
smart-ts-xl analyze --source /cobol/src --output /docs/analysis/
# Step 2: Generate dependency graph (always current)
smart-ts-xl diagram --type dependency-graph \
--format mermaid \
--output /docs/dependency-graph.md
# Step 3: Generate program inventory (always current)
smart-ts-xl report --type program-inventory \
--format markdown \
--output /docs/program-inventory.md
# Step 4: Diff against previous analysis (detect what changed)
smart-ts-xl diff \
--baseline /docs/analysis/2026-09-01/ \
--current /docs/analysis/2026-10-01/ \
--output /docs/changes/delta-report.md
Delta report, rozdíl mezi dvěma po sobě jdoucími analýzami, je protokol změn, který statický původ diagramu vytváří automaticky. Přidané programy, odebrané programy, změněné závislosti, upravené sešity: to vše se objevuje v delta reportu bez jakékoli lidské dokumentace.
Diagram vytvořený poslední analýzou představuje dokumentaci aktuální k datu analýzy. Spuštění analýzy podle plánu, týdně nebo spouštěné každým povýšením výroby vytváří dokumentaci, která je aktuální v definované kadenci, bez nutnosti průběžné ruční dokumentace.
Rámec prevence dokumentace
Předcházení dluhům z titulu neplatnosti dokumentace vyžaduje řešení pěti mechanismů pro případ neplatnosti pomocí konkrétních a implementovatelných postupů:
Proti problému akumulující se delty:
- Stanovte kadenci analýzy: týdně pro vysokorychlostní systémy, měsíčně pro stabilní systémy
- Generování dokumentace z kódu při každém spuštění analýzy, nikoli ručně
- Vytvořte delta zprávu pro každý běh, která ukazuje, co se změnilo od poslední analýzy.
Proti problému s chybějícím původem:
- Každý diagram obsahuje zdroj generování (datum a verzi analýzy kódu)
- Nikdy nepublikujte diagram bez zaznamenání, jak a kdy byl vytvořen
- Uložte generované diagramy spolu s výstupy analýz, ze kterých byly vytvořeny
Proti problému driftu vlastnictví:
- Generování dokumentace je krok v rámci procesu, nikoli individuální odpovědností.
- Dokumentace patří ropovodu; odchod žádného jednotlivce ji nenaruší.
- Vygenerovaná dokumentace nemá vlastníka, od kterého by se mohla vzdálit
Proti problému s nadměrnou přesností:
- Před vytvořením každého typu diagramu definujte jeho vhodnou úroveň abstrakce.
- Diagramy inventáře komponent na úrovni služeb/programů, nikoli na úrovni funkcí
- Vztahové diagramy na úrovni hranic domény, nikoli na úrovni jednotlivých volání
- Detailní diagramy (grafy volání, datová schémata) jsou generovány, nikoli ručně kresleny
Proti problému uzamčení formátu:
- Generované diagramy v textových formátech (Mermaid, GraphViz DOT, SVG)
- Žádná dokumentace architektury pouze ve Visiu, PowerPointu nebo PDF
- Zdrojové kódy diagramů uložené ve správě verzí spolu s kódem, který dokumentují
Jak SMART TS XL Řeší dluhy z původní dokumentace
Pro starší portfolia COBOL a mainframe, SMART TS XL je engine pro strukturální analýzu, který umožňuje dokumentaci založenou na důkazech a díky kterému je „regenerování z kódu“ praktickou alternativou k „aktualizaci diagramu SharePointu 2009“.
Funkce statické analýzy kódu analyzuje každý program v COBOLu, copybook, JCL stream a vložený SQL příkaz, aby vytvořila inventář programů, metriky složitosti a identifikaci mrtvého kódu, které tvoří základní vrstvu jakékoli přesné starší dokumentace. Tento inventář je náhradou založenou na důkazech za ručně udržovaný seznam programů, který je vždy neúplný, vždy zastaralý a vždy chybný způsoby, o kterých nikdo neví.
Mapování závislostí aplikace vytváří graf závislostí, každý vztah CALL, každý vztah COPY a každý tok dat mezi programy, což je základní artefakt dokumentace architektury. Tento graf se regeneruje z kódu při každém spuštění analýzy a vytváří tak diagram závislostí, který je aktuální k poslední analýze, bez nutnosti lidské dokumentace mezi jednotlivými spuštěními.
Funkce analýzy dopadů vytváří dokumentaci delta: když je provedena změna v kódové základně, analýza dopadů identifikuje vše, co se změnilo oproti předchozímu stavu. Jedná se o automatizovanou zprávu o delta odchylkách, která řeší problém s hromadícími se delta odchylkami. Každá změna, která by mohla rozšířit rozdíl mezi diagramem a realitou, je zachycena a automaticky zdokumentována.
Díky podpůrnému vyhledávání je dokumentace dotazovatelná: lze najít každý program, který volá konkrétní podprogram (fragment grafu volání komponenty), každý program, který obsahuje konkrétní sešit programů (rozsah závislostí sdílené komponenty), každý program upravený po určitém datu (protokol změn za určité časové období). Tato vyhledávací funkce je rozhraním pro dokumentaci, nástrojem, který odpovídá na otázky o aktuálním stavu systému na základě aktuální analýzy, nikoli na základě statického diagramu, který může být roky zastaralý.
Pro organizace provádějící starší modernizace programy, SMART TS XLGenerování dokumentace je nezbytným krokem: diagram závislostí, inventář programu a dokumentace schématu dat, kterou modernizační program potřebuje k definování rozsahu, sekvenci migračních vln a ověření výsledků. Tato dokumentace nemůže pocházet z archivu SharePointu. Musí pocházet z kódu.
Jediný přesný diagram je ten odvozený z kódu
Diagram architektury z roku 2009 na stránce SharePointu bude i nadále existovat, dokud jej někdo explicitně neodstraní. Bude i nadále odesílán novým vývojářům, když se zeptají, jak systém funguje. Bude i nadále informovat o rozhodování o systému, který již přesně nepopisuje. Rozdíl mezi diagramem a systémem se bude s každým potvrzením změny, každým nasazením, každým přidáním programu a jeho vyřazením dále zvětšovat.
Alternativou není „častější aktualizace diagramů“. Procesy, které vyžadují lidskou disciplínu k udržení funkčnosti v kódu, který se neustále mění, mají známý způsob selhání: disciplína selhává. Alternativou je dokumentace, která je odvozena z kódu, používá kód jako zdroj pravdivých informací, která se automaticky regeneruje při změně kódu a která nese časové razítko analýzy, které každému čtenáři přesně říká, jak aktuální je.
Pro moderní cloudové systémy to poskytují nástroje pro tvorbu diagramů jako kód a živou dokumentaci. Pro starší systémy COBOL to poskytuje strukturální analýza kódu. Mechanismus se liší; princip je stejný: diagram je přesný, když je odvozen z kódu, a hromadí dluh od okamžiku, kdy je oddělen od kódu, který jej vytvořil.
Jediný diagram, který zůstává aktuální, je diagram, který byl nakreslen kódem.


