Il diagramma dell'architettura presente sulla pagina di SharePoint è stato creato nel 2009. All'epoca era accurato, rifletteva il sistema così come si presentava al momento di una migrazione di piattaforma importante, disegnato da un architetto che impiegò tre settimane per documentare ogni componente e le sue relazioni. Dal 2009, il sistema ha subito circa 4,800 commit, quindici team hanno contribuito alla sua realizzazione, quattro dei componenti mostrati nel diagramma non esistono più, undici nuovi componenti sono stati aggiunti e mai rappresentati nel diagramma, e l'architetto che lo ha disegnato è andato in pensione nel 2016. Il diagramma esiste ancora. Quando un nuovo sviluppatore si unisce al team e chiede "come funziona il sistema?", qualcuno gli invia il link di SharePoint. Il diagramma non è documentazione. È archeologia.
Il debito di documentazione è un debito tecnico applicato al livello di documentazione: il divario accumulato tra ciò che la documentazione afferma su un sistema e ciò che il sistema effettivamente fa. La deriva architetturale, in cui i diagrammi si disconnettono dai sistemi che rappresentano, è la forma più comune e al contempo più pericolosa di debito di documentazione. È la più pericolosa perché genera una falsa sicurezza: un diagramma esistente e dall'aspetto professionale dà agli stakeholder l'impressione che il sistema sia compreso, quando in realtà ciò che vedono è un artefatto storico che descrive un sistema che non esiste più nella forma mostrata. I diagrammi obsoleti sono peggiori dell'assenza di diagrammi perché l'assenza di diagrammi spinge le persone a scoprire cosa c'è realmente; i diagrammi obsoleti, al contrario, spingono le persone ad agire sulla base di informazioni non più valide.
Documentazione senza sforzo
SMART TS XL Genera un registro delle modifiche di ogni programma, dipendenza e copia modificati dall'ultima esecuzione dell'analisi.
SCOPRI DI PIÙ…I cinque meccanismi che rendono obsoleti i diagrammi
Ogni articolo sulla deriva della documentazione afferma che "i diagrammi diventano obsoleti nel tempo". Quasi nessuno, però, spiega i meccanismi specifici attraverso i quali ciò avviene. Comprendere questi meccanismi è fondamentale per prevenirli, perché meccanismi diversi richiedono strategie di prevenzione diverse.
1. Il problema del delta cumulativo. Un diagramma è un'istantanea di un sistema in un determinato momento. Ogni modifica al codice successiva a tale istantanea rappresenta un delta tra il diagramma e la realtà. I singoli delta sono solitamente piccoli: un nuovo servizio, un componente rinominato, una dipendenza aggiunta. Ognuno di essi è facile da documentare singolarmente. Il problema è che nessuno li documenta in modo incrementale, perché l'aggiornamento del diagramma per ogni modifica viene percepito come un sovraccarico senza benefici immediati. Dopo 100 delta non registrati, il diagramma è sostanzialmente errato. Dopo 1,000, è sostanzialmente fittizio.
2. Il problema della provenienza mancante. Un diagramma che non ha alcun collegamento programmatico con il codice che rappresenta non ha alcun meccanismo per rilevare quando diventa inesatto. Non c'è alcun segnale che si attivi quando una modifica nel codice sorgente contraddice un'affermazione del diagramma. Il diagramma e il codice sono artefatti scollegati che descrivono lo stesso sistema, ma la connessione esiste solo nella mente di chi ha disegnato il diagramma, e solo finché queste persone se lo ricordano.
3. Il problema del trasferimento di proprietà. I diagrammi di architettura vengono in genere creati da una persona specifica in un momento specifico. Quando quella persona se ne va, la conoscenza tacita che rendeva il diagramma accurato, la comprensione di quali componenti fossero stati intenzionalmente omessi, quali relazioni fossero state semplificate, quali etichette fossero abbreviazioni per qualcosa di più complesso, se ne va con lei. Il nuovo responsabile del diagramma eredita un artefatto che non ha creato, che potrebbe non comprendere appieno e che non ha alcun incentivo a mantenere in un contesto di codice che non ha progettato.
4. Il problema del decadimento dovuto all'eccessiva precisione. I diagrammi che mostrano troppi dettagli diventano obsoleti più rapidamente rispetto a quelli che presentano un livello di astrazione adeguato. Un diagramma che mostra ogni microservizio, ogni endpoint API e ogni tabella del database deve essere aggiornato a ogni implementazione. Un diagramma che mostra i domini di servizio e i loro principali modelli di interazione deve essere aggiornato solo quando cambiano i confini del dominio. I diagrammi eccessivamente precisi hanno un'emivita di obsolescenza misurata in sprint; i diagrammi opportunamente astratti hanno un'emivita di obsolescenza misurata in trimestri.
5. Il problema del blocco del formato. I diagrammi salvati come file Visio, diapositive PowerPoint, esportazioni PNG o allegati PDF non possono essere generati, convalidati o confrontati a livello di programmazione. Non c'è modo di chiedere "questo diagramma corrisponde ancora al codice?" perché il diagramma è un'immagine pixel e il codice è testo. La scelta del formato effettuata al momento della creazione del diagramma determina se il diagramma potrà mai essere convalidato rispetto al sistema che rappresenta.
La catastrofe della documentazione del sistema legacy
Nei moderni sistemi cloud-native con team di sviluppo attivi, l'obsolescenza dei diagrammi è un problema di gestione, risolvibile con pratiche di architettura come codice, strumenti di documentazione dinamica e disciplina ingegneristica. Il sistema cambia frequentemente; il diagramma può essere aggiornato di conseguenza se il processo è corretto.
Per i sistemi legacy, il problema è diverso nella natura, non solo nell'intensità.
Un diagramma architetturale disegnato durante una revisione della progettazione di un sistema mainframe nel 1992 potrebbe aver accumulato 30 anni di modifiche al codice dalla sua creazione. Ogni anno di manutenzione attiva su un portfolio COBOL complesso produce centinaia di commit, nuovi programmi aggiunti, vecchi programmi dismessi, copybook aggiornati, flussi di job JCL riorganizzati. Il diagramma del 1992 era accurato allora. È diventato progressivamente meno accurato con il passare degli anni. Entro il 2026, il divario tra il diagramma e il sistema potrebbe essere maggiore del sistema originale stesso, e potrebbero esistere più nuovi programmi non presenti nel diagramma rispetto ai programmi del sistema originale che funzionano ancora come originariamente progettato.
Ciò che rende questa situazione catastrofica, anziché semplicemente scomoda, è il modo in cui viene utilizzato il diagramma. Quando un team di modernizzazione arriva per valutare il sistema, non sa che il diagramma è errato. Non ha modo di sapere quanto sia errato. Il diagramma sembra professionale. Presenta riquadri dei componenti, frecce di relazione, annotazioni. Suggerisce che qualcuno abbia compreso il sistema abbastanza bene da disegnarlo. Il team lo usa come punto di partenza e ogni analisi basata su un punto di partenza errato produce conclusioni errate.
Il framework di audit di Docuwriter lo spiega chiaramente: un audit della documentazione adeguato "trasforma vaghi dubbi in fatti verificabili". Per i sistemi legacy, l'audit della documentazione produce quasi sempre lo stesso risultato: i diagrammi sono assenti o talmente vecchi da rappresentare un sistema che non esiste più da anni. I fatti verificabili, quando finalmente emergono, descrivono un sistema sostanzialmente diverso da quello su cui si basava il lavoro precedente.
La specifica modalità di errore: un team di modernizzazione stima l'ambito della migrazione basandosi sullo schema del 1992. Questo schema mostra 180 componenti. L'analisi strutturale del codice sorgente effettivo rivela 340 programmi, 80 dei quali sono codice obsoleto e altri 40 sono stati aggiunti dopo il 1992 e non sono mai stati rappresentati nello schema. La stima dell'ambito era errata di un fattore due prima ancora che venisse scritta la prima riga di nuovo codice.
Categorie del diagramma in base al tasso di obsolescenza
Non tutti i diagrammi diventano obsoleti alla stessa velocità. La velocità con cui diventano obsoleti dipende da cosa rappresenta il diagramma, dalla frequenza con cui cambiano gli elementi rappresentati e dalla precisione con cui il diagramma rappresenta tali elementi.
| Tipo di diagramma | Cosa cambia frequentemente | Tasso di obsolescenza | Priorità di mitigazione |
|---|---|---|---|
| Inventario dei servizi/componenti | Nuovi servizi aggiunti, vecchi servizi dismessi. | Alto | Critico: frequenza di cambiamento più elevata |
| Mappa delle dipendenze/integrazioni | API aggiunte, integrazioni modificate, flussi di dati modificati | Alto | Critico: ogni implementazione può cambiare questo |
| Modello dati / Diagramma ER | Modifiche allo schema, nuove tabelle, modifiche alle colonne | Media altezza | Elevato: le modifiche allo schema sono frequenti nello sviluppo attivo |
| Diagrammi di sequenza | Modifiche alla logica aziendale, aggiornamenti del contratto API | Medio | Alto: qualsiasi modifica al flusso di lavoro invalida questi |
| Infrastruttura / implementazione | L'infrastruttura come codice favorisce i cambiamenti frequenti | Alto | Medio — Gli strumenti IaC possono generare automaticamente questi |
| Dominio / contesto delimitato | Cambiamenti organizzativi e di proprietà | Basso-medio | Basso — i confini del dominio cambiano trimestralmente o meno |
| Registri delle decisioni (ADR) | Raramente si verificano cambiamenti (le decisioni sono storiche). | Molto basso | Basso: una volta registrato correttamente, rimane preciso. |
| Grafico delle chiamate di programma (COBOL) | Ogni modifica al codice potenzialmente modifica questo | Molto alto | Fondamentale per l'eredità: cambiamenti invisibili |
| Manuale/schema (COBOL) | Ogni modifica FD influisce su più programmi | Alto | Fondamentale per la continuità del progetto: i cambiamenti si propagano silenziosamente |
Le ultime due righe contengono le voci specifiche del sistema legacy, per le quali non esiste alcuna documentazione standard. Un diagramma delle chiamate di un programma COBOL può essere invalidato da ogni modifica al codice di qualsiasi programma nell'albero delle chiamate. Un copybook condiviso da 200 programmi viene invalidato per ogni programma quando il copybook viene modificato. Questi diagrammi presentano il più alto tasso di obsolescenza in qualsiasi portfolio aziendale e le conseguenze più gravi quando sono obsoleti, perché i programmi che descrivono sono quelli che eseguono i processi aziendali più critici.
La soluzione Provenance: tracciare i diagrammi fino alla loro origine
La causa principale del debito di documentazione non è l'assenza di un processo di aggiornamento della documentazione, bensì l'assenza di provenienza, ovvero il collegamento tracciabile tra un elemento del diagramma e l'artefatto di codice che esso rappresenta. Senza provenienza, non esiste un meccanismo per rilevare l'obsolescenza. Con la provenienza, il rilevamento dell'obsolescenza è automatico: se l'artefatto di codice è cambiato da quando il diagramma è stato generato, il diagramma è obsoleto.
La provenienza nella documentazione esiste a due livelli:
Provenienza statica è la documentazione generata dal codice in un determinato momento, con un timestamp di generazione e un riferimento allo stato del codice (hash del commit, versione, data di analisi) che la documentazione riflette. La provenienza statica non impedisce l'obsolescenza, ma la rende rilevabile: il timestamp mostra che la documentazione è stata generata dal commit abc123 in una data specifica e il commit corrente è def456 in una data successiva. L'intervallo tra i due commit è l'intervallo tra la documentazione e il codice corrente.
La provenienza dinamica è una documentazione generata continuamente dal codice, rigenerata a ogni modifica rilevante. La documentazione è sempre aggiornata perché deriva costantemente dallo stato attuale del codice. Questo è il modello di documentazione vivente, non diagrammi che qualcuno aggiorna quando se ne ricorda, ma diagrammi che vengono rigenerati dal codice ogni volta che questo cambia.
La differenza pratica per un portfolio COBOL legacy: un approccio di provenienza statica genera il diagramma delle dipendenze dall'analisi corrente del codice sorgente COBOL e lo contrassegna con un timestamp. Ogni settimana, l'analisi può essere rieseguita e il nuovo diagramma confrontato con il precedente. Le modifiche sono visibili come differenze tra i risultati consecutivi dell'analisi. Un approccio di provenienza dinamica integra l'analisi nella pipeline di gestione delle modifiche del mainframe, generando un diagramma aggiornato ogni volta che un programma viene promosso in produzione.
Diagrammi come codice: cosa funziona e cosa manca
La risposta moderna ai diagrammi statici e obsoleti è rappresentata dai diagrammi come codice, che esprimono la documentazione architetturale in un formato testuale che può essere gestito tramite controllo di versione, confronto, revisione e generazione programmatica. Mermaid, PlantUML e il modello C4 in forma di codice sono gli strumenti principali.
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
Questo diagramma Mermaid si trova nel repository, insieme al codice che rappresenta. Quando uno sviluppatore aggiunge un nuovo servizio, aggiorna questo file nella stessa pull request. La revisione del codice include la modifica del diagramma. La documentazione e il codice viaggiano insieme.
Cosa non risolve la codifica dei diagrammi:
Non risolve il problema della documentazione dei sistemi legacy. Un programma COBOL aggiunto a una libreria mainframe da uno sviluppatore che invia un JCL compilato anziché una pull request Git non attiva un aggiornamento del file Mermaid. Il processo di gestione delle modifiche del mainframe e il processo di documentazione basato su Git sono sistemi separati senza sincronizzazione automatica.
Non risolve il problema dell'eccessiva precisione. Un diagramma Mermaid che deve essere aggiornato manualmente per ogni nuovo servizio richiede comunque la disciplina umana che il processo avrebbe dovuto sostituire. Se l'aggiornamento del diagramma è un passaggio manuale, verrà saltato.
Non corregge retroattivamente i diagrammi preesistenti. Per un portfolio COBOL privo di documentazione leggibile automaticamente, la funzionalità "diagrammi come codice" fornisce una struttura per la documentazione futura, ma non produce la documentazione corrente.
L'approccio di analisi strutturale per i sistemi legacy
Per i sistemi legacy in cui la rappresentazione grafica del codice tramite diagrammi non è praticabile, perché il flusso di lavoro di sviluppo non passa attraverso Git, perché la documentazione esistente è troppo obsoleta per essere il punto di partenza per un approccio basato sul testo, o perché il codice sorgente non è mai stato formalmente documentato, l'analisi strutturale del codice è l'unico meccanismo in grado di produrre una documentazione aggiornata e accurata partendo da zero.
L'analisi strutturale esamina il codice sorgente, i programmi COBOL, i flussi di lavoro JCL, i copybook e il codice SQL incorporato, ricavando direttamente dal codice le relazioni di dipendenza, gli inventari dei programmi e le strutture dati. Il risultato non è un diagramma disegnato da una persona che ha compreso il codice, bensì un diagramma derivato algoritmicamente dal codice stesso. La sua accuratezza è limitata dall'accuratezza dell'analisi, non dalla memoria dello sviluppatore che lo ha realizzato.
Il flusso di lavoro:
bash
# 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
Il report delta, ovvero la differenza tra due analisi consecutive, è il registro delle modifiche generato automaticamente dalla provenienza statica del diagramma. Programmi aggiunti, programmi rimossi, dipendenze modificate, copybook modificati: tutto viene visualizzato nel report delta senza alcun intervento manuale di documentazione.
Il diagramma prodotto dall'ultima analisi rappresenta la documentazione aggiornata alla data dell'analisi stessa. Eseguendo l'analisi a intervalli regolari, settimanalmente o in corrispondenza di ogni promozione di produzione, si ottiene una documentazione sempre aggiornata con una cadenza definita, senza la necessità di un continuo lavoro manuale di documentazione.
Il quadro di riferimento per la prevenzione della documentazione
Prevenire i debiti documentali richiede di affrontare i cinque meccanismi di obsolescenza con pratiche specifiche e attuabili:
Contro il problema del delta cumulativo:
- Definire una cadenza di analisi: settimanale per i sistemi ad alta velocità, mensile per quelli stabili.
- Genera la documentazione dal codice ad ogni esecuzione dell'analisi, non manualmente.
- Genera un report differenziale per ogni esecuzione, mostrando le modifiche apportate dall'ultima analisi.
Contro il problema della provenienza mancante:
- Ogni diagramma include la sua fonte di generazione (data e versione dell'analisi del codice).
- Non pubblicare mai un diagramma senza aver prima registrato come e quando è stato realizzato.
- Archivia i diagrammi generati insieme ai risultati dell'analisi che li hanno prodotti.
Contro il problema della deriva della proprietà:
- La generazione della documentazione è una fase del processo, non una responsabilità individuale.
- La documentazione appartiene all'oleodotto; la partenza di qualsiasi singolo individuo ne compromette la validità.
- La documentazione generata non ha un proprietario da cui allontanarsi
Contro il problema dell'eccessiva precisione:
- Definisci il livello di astrazione appropriato per ogni tipo di diagramma prima di crearlo
- Diagrammi di inventario dei componenti a livello di servizio/programma, non a livello di funzione.
- Diagrammi delle relazioni a livello di confine del dominio, non a livello di singola chiamata
- Vengono generati diagrammi dettagliati (grafici delle chiamate, schemi dei dati), non disegnati a mano.
Contro il problema del blocco del formato:
- Diagrammi generati in formati testuali (Mermaid, GraphViz DOT, SVG)
- Nessuna documentazione architettonica in formato Visio, PowerPoint o PDF.
- I file sorgente dei diagrammi vengono archiviati nel sistema di controllo versione insieme al codice che documentano.
Come SMART TS XL Affronta il problema del debito relativo alla documentazione pregressa
Per i portfolio COBOL legacy e mainframe, SMART TS XL è il motore di analisi strutturale che rende possibile la documentazione basata su dati concreti e che trasforma la "rigenerazione dal codice" in un'alternativa pratica all'"aggiornamento del diagramma di SharePoint 2009".
La funzionalità di analisi statica del codice analizza ogni programma COBOL, copybook, job stream JCL e istruzione SQL incorporata per produrre l'inventario dei programmi, le metriche di complessità e l'identificazione del codice morto, elementi che costituiscono la base di qualsiasi documentazione legacy accurata. Questo inventario rappresenta la valida alternativa, basata su dati concreti, all'elenco di programmi gestito manualmente, che è sempre incompleto, sempre obsoleto e sempre errato in modi di cui nessuno è a conoscenza.
La mappatura delle dipendenze dell'applicazione genera il grafo delle dipendenze, che mostra ogni relazione CALL, ogni relazione COPY e ogni flusso di dati tra i programmi, elemento fondamentale della documentazione architetturale. Questo grafo viene rigenerato dal codice a ogni esecuzione dell'analisi, producendo un diagramma delle dipendenze aggiornato all'ultima analisi, senza necessità di alcun intervento manuale di documentazione tra un'esecuzione e l'altra.
La funzionalità di analisi d'impatto genera la documentazione delta: quando viene apportata una modifica al codice sorgente, l'analisi d'impatto identifica tutto ciò che è cambiato rispetto allo stato precedente. Si tratta di un report delta automatizzato che affronta il problema dell'accumulo delta: ogni modifica che avrebbe ampliato il divario tra diagramma e realtà viene rilevata e documentata automaticamente.
La funzionalità di ricerca aziendale rende la documentazione interrogabile: è possibile trovare ogni programma che richiama una specifica sottoprogramma (il frammento del grafico delle chiamate per un componente), ogni programma che include uno specifico copybook (l'ambito delle dipendenze di un componente condiviso), ogni programma modificato dopo una data specifica (il registro delle modifiche per un determinato periodo). Questa funzionalità di ricerca rappresenta l'interfaccia della documentazione, lo strumento che risponde alle domande sullo stato attuale del sistema a partire dall'analisi corrente, non da un diagramma statico che potrebbe essere obsoleto da anni.
Per le organizzazioni che conducono modernizzazione dell'eredità programmi, SMART TS XLLa generazione della documentazione è il prerequisito fondamentale: il diagramma delle dipendenze, l'inventario dei programmi e la documentazione dello schema dati sono necessari al programma di modernizzazione per definire l'ambito, sequenziare le fasi di migrazione e convalidare i risultati. Questa documentazione non può provenire dall'archivio di SharePoint, ma deve essere ricavata dal codice.
L'unico diagramma accurato è quello derivato dal codice
Il diagramma dell'architettura del 2009 presente sulla pagina di SharePoint continuerà a esistere finché qualcuno non lo eliminerà esplicitamente. Continuerà a essere inviato ai nuovi sviluppatori quando chiederanno come funziona il sistema. Continuerà a influenzare le decisioni relative a un sistema che non descrive più accuratamente. Il divario tra il diagramma e il sistema continuerà ad ampliarsi con ogni commit, ogni implementazione, ogni aggiunta e dismissione di un programma.
L'alternativa non è "aggiornare i diagrammi più spesso". I processi che richiedono disciplina umana per essere mantenuti in un contesto in cui il codice cambia continuamente presentano una modalità di fallimento nota: la disciplina viene meno. L'alternativa è una documentazione derivata dal codice, che utilizza il codice come fonte di verità, che si rigenera automaticamente quando il codice cambia e che riporta la data e l'ora dell'analisi, indicando a ogni lettore con precisione quanto sia aggiornata.
Per i moderni sistemi cloud, questo è possibile grazie ai diagrammi come codice e agli strumenti di documentazione dinamica. Per i sistemi COBOL legacy, invece, è l'analisi strutturale del codice a fornirlo. Il meccanismo è diverso, ma il principio è lo stesso: il diagramma è accurato quando viene derivato dal codice e accumula errori dal momento in cui viene separato dal codice che lo ha generato.
L'unico diagramma che rimane aggiornato è quello disegnato dal codice.


