Transparency for Legacy Replacement: Automated Software Documentation

Replacing enterprise software that has grown over decades has become a task that even large project teams can hardly complete within a manageable time frame. The reason rarely lies in the new technology but in the old system: nobody can say reliably what it does. This article shows why automated software documentation is a decisive lever for legacy replacement, what auditors require, and how we bring transparency into existing systems with Sysparency.

Why the replacement of grown systems stalls

At the core of most organizations runs a historically grown enterprise software. These ERP and core systems are the beating heart of the entire IT architecture that has developed around them over decades. Without them, no data flows into the many business services built on top. Instead of renewing the system to the current state of technology, whatever was needed at the time was added over the years: new functions, further programming languages, product-specific technology stacks. System complexity has risen dramatically as a result, and the whole is understood only by a small circle of insiders.

At the same time, organizations are deploying more and more intelligent software algorithms that learn on their own and make decisions without human intervention. In the book "Das selbstfahrende Unternehmen" (Springer Gabler 2021), I described that the acceptance of these algorithms depends on their traceability: what is not understood is pulled into the mystical and rejected. The two problems overlap. The new algorithms must be explainable, and the old systems they connect to are not. Before cognitive software is placed on a foundation, that foundation must be transparent.

In the book, I classified robotic process automation as a bridging technology: software robots bridge the gap between legacy systems and new applications as long as the replacement is still pending. A bridge, however, is no substitute for a new building. At some point the legacy system has to be replaced, and every year an organization waits makes that replacement more expensive.

Insight only for the initiated: the source code problem

In many organizations, the source code of enterprise software that has often been in use for decades is treated like "the holy of holies." Only a few people have access to it, and even fewer are able to read and understand it. This creates bottlenecks in exactly those resources a replacement needs most urgently: experienced developers who know the system. Many of them are close to retirement, and their knowledge is often written down nowhere.

Requirements analysts can capture the actual application in its full complexity only in fragments. From the patchy documentation, management forms a false picture of the existing software, usually an oversimplified one. Our practice shows that with manual documentation, even after five years only a fraction of a large legacy system is described. This makes every maintenance task, every enhancement, and above all a complete replacement extremely laborious and expensive. Many organizations are deterred by this and cling to the existing solution. The replacement scenario is inevitable, but it is suppressed.

What auditors require

The central argument for automated documentation does not come from IT but from auditing. In system-critical industries such as banking, insurance, energy supply, and healthcare, organizations are obliged to document the software in use in such a way that its essential aspects are externally auditable and traceable. For the financial sector, the supervisory requirements are unambiguous: the German BaFin's Supervisory Requirements for IT in Financial Institutions (BAIT) and the EBA Guidelines on ICT and security risk management demand up-to-date documentation of applications and the business processes they support. With Regulation (EU) 2022/2554 on digital operational resilience for the financial sector (DORA), in force since January 2023 and applicable from January 2025, the identification and documentation of all ICT-supported business functions and information assets becomes mandatory for financial entities across Europe.

From the auditors' point of view, the requirements for system documentation can be summarized as follows:

• Complete. All programs, interfaces, and data flows are captured, not only the known ones.
• Current. The documentation describes the state of the productive system, not the state of the last major projects.
• Understandable. People with business expertise but without IT expertise can read and assess the description.
• Evidenced. Every statement can be traced back to the source code it comes from.
• Repeatable. The documentation can be renewed for the next audit without a new major project.

Manually created documentation regularly fails on the first two points. It is already outdated on the day it is completed and covers only what the team was able to capture in the available time. I expect the legal framework to be tightened further and that for system-critical software an automatically generated documentation, including the software architecture, will have to be presented in the future. Without this basis, an objective and reliable audit is not possible.

Case study: a bank's legacy dilemma

A typical, anonymized example from our consulting practice: the head of central IT at a bank is responsible for a core system that has grown over decades and whose components were largely developed and extended in-house. The system is critical for the bank and its customers, but it lacks adequate documentation. External auditors have already recorded this as a finding several times. The bank faces the task of replacing the system within five years.

The first step, and at the same time the planning basis for all further steps, is a current analysis and documentation of the software's actual behavior. This step alone was calculated at around three years for a complete software development team and would have consumed nearly one third of the entire replacement budget. That seemed unrealistic, but for a project of this magnitude, no other path was initially apparent.

With automated software documentation, the starting position looked different (empirical values from Sysparency and ReqPOOL projects, verifiable per project):

1. Analysis from the code. Sysparency systematically analyzes the historically grown system on the basis of its program code and documents it automatically.
2. Audit-ready documentation. Together with the experts at Sysparency, the documentation required for the audit is produced on time.
3. Relief for the replacement team. The team carries only a fraction of the originally calculated effort, and the replacement budget shrinks accordingly.
4. Business units stay in daily operations. About one third of the IT experts from the business units did not have to be involved in the project because the documentation base was stable without them.

The first step is thus completed not only faster and with fewer resources. The professionally prepared documentation base eases and accelerates all further steps of the replacement: specification, tendering, migration, and acceptance.

How automated documentation works

Sysparency is a scientific spin-off from Linz and a partner company of ReqPOOL. The analysis software reads the source code of a legacy system and derives from it the entire structure and the functions of the system, largely regardless of the programming language and the age of the code. The prerequisite is full accessibility of the system for all members of the project team. On this basis, three perspectives on the same system emerge within a short time:

Projects often begin as early as the discovery phase. Even before precise specification and planning, all system risks are identified because the software is captured in its full functionality. Risks can thus be addressed early, and management receives a sound basis for deciding whether and how the replacement project is feasible in budget, scope, and time.

The benefit grows with the size of the system. As project size increases, additional manpower leads to considerable communication problems, an effect Frederick Brooks described as early as 1975 in "The Mythical Man-Month." An automated solution, by contrast, scales unhindered with complexity. Depending on the size of the project, up to 90 percent of the effort can be saved compared with manually created documentation, and the documentation is available in a fraction of the time. As a result, development and replacement processes accelerate by up to one third (empirical values from Sysparency projects, verifiable per project).

One aspect is particularly important to me: unlike people and teams, the software has no interests of its own. It documents what the code does, not what someone remembers or would like to be the case. Gaps and special cases become visible instead of being glossed over. Since ChatGPT, we are frequently asked whether a language model could not simply explain the code. For individual functions, that is a help. Audit-ready documentation of millions of lines of code, however, requires a systematic, complete, and repeatable analysis whose result can be traced back to every line. Language models can build on that foundation; they do not replace it.

Transparency as a precursor of the self-driving company

In the previous article of this series, I described transparency as a principle of the self-driving company: all data and facts are available in real time, and unfavorable practices can no longer be concealed. The automated documentation of legacy systems is the tangible precursor to this. It first makes visible what is already running today.

In the book, I formulated a consequence for the company of 2035 that strikes many as radical at first glance:

Likewise, the auditor becomes superfluous, because these systems are completely transparent.

In 2023 we are far from that. Today, auditors criticize missing documentation, and organizations laboriously produce it after the fact. In the self-driving company, documentation is no longer a downstream project but a property of the software itself: the system can explain at any time what it does and why. The path there does not begin with new algorithms but with the readability of the existing ones. Those who know their legacy system completely can decide what to carry into the future and what not, and can justify that decision to supervisors, owners, and staff.

The next step

How transparency, algorithms, and enterprise architecture interact in the self-driving company is described in the book "Das selbstfahrende Unternehmen": About the book. If you are facing the replacement of a grown system or have an open audit finding on documentation, we will clarify in a conversation how an automated documentation base shortens your project: Book an expert meeting.