Documentation Debt: Why Diagrams Go Stale and How to Prevent It

The architecture diagram on the SharePoint page was created in 2009. It was accurate then, it reflected the system as it existed at the time of a major platform migration, drawn by an architect who spent three weeks documenting every component and its relationships. Since 2009, the system has received approximately 4,800 commits, fifteen teams have contributed to it, four of the components shown on the diagram no longer exist, eleven new components were added and never diagrammed, and the architect who drew it retired in 2016. The diagram still exists. When a new developer joins and asks “how does the system work?”, someone sends them the SharePoint link. The diagram is not documentation. It is archaeology.

Documentation debt is technical debt applied to the documentation layer: the accumulated gap between what documentation says about a system and what the system actually does. Architecture drift, where diagrams disconnect from the systems they depict, is both the most common and the most dangerous form of documentation debt. It is the most dangerous because it presents false confidence: a diagram that exists and looks professional gives stakeholders the impression that the system is understood, when what they are actually seeing is a historical artifact that describes a system that no longer exists in the form shown. Outdated diagrams are worse than no diagrams because no diagrams prompt people to find out what is actually there; outdated diagrams prompt people to act on what is no longer true.

The Five Mechanisms That Make Diagrams Go Stale

Every article on documentation drift says “diagrams go stale over time.” Almost none explain the specific mechanisms through which this happens. Understanding the mechanisms is prerequisite to preventing them, because different mechanisms require different prevention strategies.

1. The accumulating delta problem. A diagram is a snapshot of a system at a point in time. Every code change after that snapshot is a delta between the diagram and reality. Individual deltas are usually small, a new service, a renamed component, a dependency added. Each is easy to document in isolation. The problem is that no one documents them incrementally, because updating the diagram for each change is perceived as overhead without immediate benefit. After 100 unrecorded deltas, the diagram is materially wrong. After 1,000, it is substantially fictional.

2. The missing provenance problem. A diagram that has no programmatic link to the code it depicts has no mechanism for detecting when it becomes inaccurate. There is no signal that fires when a change in the codebase contradicts a claim in the diagram. The diagram and the code are disconnected artifacts that happen to describe the same system, but the connection exists only in the minds of the people who drew the diagram, and only for as long as those people remember it.

3. The ownership drift problem. Architecture diagrams are typically created by a specific person at a specific moment. When that person leaves, the tacit knowledge that made the diagram accurate, the understanding of which components were intentionally omitted, which relationships were simplified, which labels were shorthand for something more complex, leaves with them. The diagram’s new custodian inherits an artifact they did not create, may not understand fully, and has no incentive to maintain against a codebase they did not design.

4. The over-precision decay problem. Diagrams that show too much detail go stale faster than diagrams that show appropriate abstraction. A diagram that shows every microservice, every API endpoint, and every database table needs to be updated for every deployment. A diagram that shows service domains and their primary interaction patterns needs to be updated only when domain boundaries change. Over-precise diagrams have a staleness half-life measured in sprints; appropriately abstracted diagrams have a staleness half-life measured in quarters.

5. The format lock-in problem. Diagrams stored as Visio files, PowerPoint slides, PNG exports, or PDF attachments cannot be generated, validated, or compared programmatically. There is no way to ask “does this diagram still match the code?” because the diagram is a pixel image and the code is text. The format choice made at diagram creation determines whether the diagram can ever be validated against the system it depicts.

The Legacy System Documentation Catastrophe

For modern cloud-native systems with active development teams, diagram staleness is a management problem, solved with architecture-as-code practices, living documentation tooling, and engineering discipline. The system changes frequently; the diagram can be updated to match if the process is right.

For legacy systems, the problem is different in kind, not just in degree.

An architecture diagram drawn during a mainframe system design review in 1992 may have accumulated 30 years of code changes since its creation. Each year of active maintenance on a complex COBOL portfolio produces hundreds of commits, new programs added, old programs retired, copybooks updated, JCL job streams reorganized. The diagram from 1992 was accurate then. It has been progressively less accurate for every year since. By 2026, the gap between the diagram and the system may be larger than the original system itself, more new programs exist that are not on the diagram than programs from the original system that still run as originally designed.

What makes this catastrophic rather than merely inconvenient is how the diagram is used. When a modernization team arrives to assess the system, they do not know the diagram is wrong. They have no way of knowing how wrong it is. The diagram looks professional. It has component boxes, relationship arrows, annotations. It suggests that someone understood this system well enough to draw it. The team uses it as their starting point, and every analysis built on a wrong starting point produces wrong conclusions.

The Docuwriter audit framework puts it clearly: a proper documentation audit “turns vague unease into inspectable facts.” For legacy systems, the documentation audit almost always produces the same finding: the diagrams are either absent or so old that they represent a system that has not existed for years. The inspectable facts, when they are finally surfaced, describe a system substantially different from what anyone was working from.

The specific failure mode: a modernization team estimates the migration scope from the 1992 diagram. It shows 180 components. The structural analysis of the actual codebase reveals 340 programs, 80 of which are dead code and another 40 of which were added after 1992 and were never diagrammed. The scope estimate was wrong by a factor of two before the first line of new code was written.

Diagram Categories by Staleness Rate

Not all diagrams go stale at the same rate. The staleness rate depends on what the diagram depicts, how frequently the depicted elements change, and how precisely the diagram represents those elements.

Diagramtyp	What Changes Frequently	Staleness Rate	Prioritet för begränsning
Service/component inventory	New services added, old services retired	Hög	Critical — highest change frequency
Dependency/integration map	APIs added, integrations changed, data flows modified	Hög	Critical — every deployment can change this
Data model / ERD	Schema changes, new tables, column modifications	Medelhög	High — schema changes are frequent in active development
Sequence diagrams	Business logic changes, API contract updates	Medium	High — any workflow change invalidates these
Infrastructure / deployment	Infra-as-code drives frequent change	Hög	Medium — IaC tools can auto-generate these
Domain / bounded context	Organizational and ownership changes	Låg-medium	Low — domain boundaries change quarterly or less
Decision records (ADRs)	Rarely change (decisions are historical)	Väldigt låg	Low — once recorded correctly, stays accurate
Program call graph (COBOL)	Every code change potentially changes this	Mycket högt	Critical for legacy — changes invisibly
Copybook / schema (COBOL)	Every FD change affects multiple programs	Hög	Critical for legacy — changes cascade silently

The bottom two rows are the legacy-specific entries that no standard documentation guidance addresses. A COBOL program call graph is potentially invalidated by every code change to any program in the call tree. A copybook shared by 200 programs is invalidated for every program when the copybook changes. These diagrams have the highest staleness rate in any enterprise portfolio and the most severe consequences when stale, because the programs they describe are the ones running the most critical business processes.

The Provenance Solution: Tracing Diagrams to Their Source

The root cause of documentation debt is not the absence of a documentation update process. It is the absence of provenance, the traceable link from a diagram element to the code artifact it depicts. Without provenance, there is no mechanism for detecting staleness. With provenance, staleness detection is automatic: if the code artifact has changed since the diagram was generated, the diagram is stale.

Provenance in documentation exists at two levels:

Static provenance is documentation generated from code at a point in time, with a generation timestamp and a reference to the code state (commit hash, version, analysis date) that the documentation reflects. Static provenance does not prevent staleness, but it makes staleness detectable: the timestamp shows that the documentation was generated from commit abc123 on a specific date, and the current commit is def456 on a later date. The gap between the two commits is the gap between the documentation and the current code.

Dynamic provenance is documentation generated continuously from code, regenerated on every relevant code change. The documentation is always current because it is always derived from the current code state. This is the living documentation model, not diagrams that someone updates when they remember to, but diagrams that are regenerated from the code whenever the code changes.

The practical difference for a legacy COBOL portfolio: a static provenance approach generates the dependency diagram from the current COBOL source analysis and timestamps it. Every week, the analysis can be re-run and the new diagram compared to the previous one. Changes are visible as differences between consecutive analysis outputs. A dynamic provenance approach integrates the analysis into the mainframe change management pipeline, generating an updated diagram whenever a program is promoted to production.

Diagrams-as-Code: What Works and What It Misses

The modern response to stale static diagrams is diagrams-as-code, expressing architectural documentation in a text format that can be version-controlled, diffed, reviewed, and generated programmatically. Mermaid, PlantUML, and the C4 model in code form are the primary tools.

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

This Mermaid diagram lives in the repository, alongside the code it depicts. When a developer adds a new service, they update this file in the same pull request. The code review includes the diagram change. The documentation and the code travel together.

What diagrams-as-code does not solve:

It does not solve legacy system documentation. A COBOL program added to a mainframe library by a developer who submits compile JCL rather than a Git pull request does not trigger a Mermaid file update. The mainframe change management process and the Git-based documentation process are separate systems with no automatic synchronization.

It does not solve the over-precision problem. A Mermaid diagram that must be manually updated for every new service still requires the human discipline that the process was supposed to replace. If updating the diagram is a manual step, it will be skipped.

It does not retroactively fix legacy diagrams. For a COBOL portfolio with no existing machine-readable documentation, diagrams-as-code provides a framework for future documentation but does not produce the current documentation.

The Structural Analysis Approach for Legacy Systems

For legacy systems where diagrams-as-code is impractical, because the development workflow does not pass through Git, because the existing documentation is too far out of date to be the starting point for a text-based approach, or because the codebase was never formally documented, structural code analysis is the only mechanism that produces current, accurate documentation from a standing start.

Structural analysis parses the actual code, COBOL programs, JCL job streams, copybooks, embedded SQL, and derives the dependency relationships, program inventories, and data structures directly from what the code contains. The output is not a diagram drawn by a human who understood the code; it is a diagram derived algorithmically from the code itself. Its accuracy is bounded by the accuracy of the analysis, not by the memory of the developer who drew it.

Arbetsflödet:

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

The delta report, the diff between two consecutive analyses, is the change log that the diagram’s static provenance produces automatically. Programs added, programs removed, dependencies changed, copybooks modified: all appear in the delta report without any human documentation effort.

The diagram produced by the last analysis is the documentation that is current as of the analysis date. Running the analysis on a schedule, weekly, or triggered by every production promotion, produces documentation that is current at a defined cadence without any ongoing manual documentation effort.

The Documentation Prevention Framework

Preventing documentation debt requires addressing the five staleness mechanisms with specific, implementable practices:

Against the accumulating delta problem:

• Establish an analysis cadence: weekly for high-velocity systems, monthly for stable ones
• Generate documentation from code on every analysis run, not manually
• Produce a delta report on each run showing what changed since the last analysis

Against the missing provenance problem:

• Every diagram includes its generation source (code analysis date and version)
• Never publish a diagram without recording how and when it was produced
• Store generated diagrams alongside the analysis outputs that produced them

Against the ownership drift problem:

• Documentation generation is a pipeline step, not an individual responsibility
• The pipeline owns the documentation; no individual’s departure breaks it
• Generated documentation has no owner to drift away from

Against the over-precision problem:

• Define the appropriate abstraction level for each diagram type before creating it
• Component inventory diagrams at the service/program level, not the function level
• Relationship diagrams at the domain boundary level, not the individual call level
• Detailed diagrams (call graphs, data schemas) are generated, not hand-drawn

Against the format lock-in problem:

• Generated diagrams in text-based formats (Mermaid, GraphViz DOT, SVG)
• No architecture documentation in Visio, PowerPoint, or PDF alone
• Diagram sources stored in version control alongside the code they document

Hur SMART TS XL Addresses Legacy Documentation Debt

For legacy COBOL and mainframe portfolios, SMART TS XL is the structural analysis engine that makes evidence-based documentation possible, and that makes “regenerate from the code” a practical alternative to “update the 2009 SharePoint diagram.”

Ocuco-landskapet statisk kodanalys capability parses every COBOL program, copybook, JCL job stream, and embedded SQL statement to produce the program inventory, complexity metrics, and dead code identification that form the base layer of any accurate legacy documentation. This inventory is the evidence-based replacement for the manually maintained program list that is always incomplete, always out of date, and always wrong in ways nobody knows about.

Ocuco-landskapet mappning av applikationsberoenden produces the dependency graph, every CALL relationship, every COPY relationship, every data flow between programs, that is the core artifact of architecture documentation. This graph is regenerated from the code on every analysis run, producing a dependency diagram that is current as of the last analysis without any human documentation effort between runs.

Ocuco-landskapet konsekvensanalys capability produces the delta documentation: when a change is made to the codebase, the impact analysis identifies everything that changed relative to the previous state. This is the automated delta report that addresses the accumulating delta problem, every change that would have widened the diagram-reality gap is captured and documented automatically.

Ocuco-landskapet företagssökning capability makes the documentation queryable: find every program that calls a specific subprogram (the call graph fragment for a component), every program that includes a specific copybook (the dependency scope of a shared component), every program modified after a specific date (the change log for a time period). This search capability is the documentation interface, the tool that answers questions about the current system state from the current analysis, not from a static diagram that may be years out of date.

För organisationer som bedriver äldre modernisering program, SMART TS XL’s documentation generation is the prerequisite step: the dependency diagram, program inventory, and data schema documentation that the modernization program needs to define scope, sequence migration waves, and validate outcomes. This documentation cannot come from the SharePoint archive. It must come from the code.

The Only Accurate Diagram Is the One Derived From the Code

The 2009 architecture diagram on the SharePoint page will continue to exist until someone explicitly deletes it. It will continue to be sent to new developers when they ask how the system works. It will continue to inform decisions about a system it no longer accurately describes. The gap between the diagram and the system will continue to widen with every commit, every deployment, every program addition and retirement.

The alternative is not “update the diagrams more often.” Processes that require human discipline to maintain against code that changes continuously have a known failure mode: the discipline fails. The alternative is documentation that is derived from the code, that uses the code as its source of truth, that regenerates automatically when the code changes, and that carries the analysis timestamp that tells every reader exactly how current it is.

For modern cloud systems, diagrams-as-code and living documentation tooling provide this. For legacy COBOL systems, structural code analysis provides it. The mechanism differs; the principle is the same: the diagram is accurate when it is derived from the code, and it accumulates debt from the moment it is separated from the code that produced it.

The only diagram that stays current is the diagram that was drawn by the code.