In banks and insurance companies, a significant share of processing runs on applications built a long time ago. They work, they carry precise business rules, and their documentation is often incomplete or out of date. The people who designed them have sometimes left the company.
When the time comes to modernise, migrate or replace these applications, one question comes before all others: what exactly does the system do today? Reverse documentation exists to answer it.
What reverse documentation means
Reverse documentation means rebuilding, from the existing system, a reliable description of what it does. The work starts from the code, data schemas, batch chains, configuration and exchanges with other applications. It also draws on interviews with users and operations teams.
The result is a set of documents describing the system as it actually works today. This matters: over the years, fixes, regulatory changes and workarounds have altered how the application actually behaves.
Why modernisation depends on it
A modernisation project compares a current state with a target state. If the current state is poorly understood, several problems appear.
Lost business rules
A calculation rule, an exception for a category of contracts, a control added after an incident: these often exist only in the code. If they are not identified, the new system does not reproduce them, and the gap surfaces during acceptance testing or after go-live.
Fragile estimates
Without a precise inventory of functions, interfaces and volumes, the cost of a migration rests on assumptions. Overruns in effort and schedule often trace back to a scope that was poorly known at the start.
Acceptance testing that is hard to build
To check that the new system behaves correctly, you need to know what the old one did. Reverse documentation provides the basis for test cases and acceptance criteria.
Dependence on a few people
When knowledge sits with two or three experts, every absence slows the project. Documenting reduces that risk and makes it easier to bring in new people.
Scoping the work
Reverse documentation can turn into an endless task if it is not scoped. A few decisions should be made at the outset.
Define what the documentation is for
Documentation for a technical migration, a functional redesign or an audit is not the same. The purpose sets the expected level of detail: flow descriptions for a map of the landscape, detailed business rules for a rewrite, data mappings for a migration.
Set the boundaries
List the applications, modules, processes and interfaces in scope, and explicitly exclude what is out of scope. A written scope prevents silent expansion.
Choose the deliverables
Typical deliverables are an application map, a data dictionary, a description of processes and how they chain together, a catalogue of business rules and a list of interfaces. The format should be agreed in advance and validated by the people who will use the documents.
Identify sources and contacts
Access to source code and environments, existing documentation even if partial, availability of business experts and operations teams: these conditions should be checked before starting, because they set the pace of the work.
Start with a sample
In our engagements, we recommend not launching full reverse documentation straight away. We suggest starting with a representative sample: one module, one batch chain or one functional domain.
The sample serves several purposes:
- validating the deliverable format with its future readers before rolling it out;
- measuring the actual effort per documented unit, which gives a grounded estimate for the rest of the scope;
- revealing difficulties specific to the system: poorly structured code, external configuration, undocumented dependencies;
- giving the client a concrete deliverable to judge the quality of the work before committing further.
The sample should be chosen for how representative it is. A module that is too simple produces an optimistic estimate; an unusually complex one produces a pessimistic estimate. A good choice is often an ordinary module with a few meaningful business rules and at least one interface.
Points to watch
Check with users
The code shows what the system does. Users show what is actually used, what is worked around and what has become obsolete. Both sources are needed.
Separate observation from interpretation
Reverse documentation describes what exists. Anomalies, or rules that look outdated, should be flagged as such without being corrected in the description. Whether to keep them is a decision for the modernisation project.
Keep the documentation current
If the existing system keeps changing during the project, the documentation must follow. A simple update process, tied to delivered changes, keeps it from going stale before the migration is complete.
Protect the data
Working on an existing system gives access to real data. Reverse documentation should be carried out within the client’s environment, using test or anonymised data wherever possible.
In short
Reverse documentation is a quiet step. It turns scattered knowledge into a shared foundation on which modernisation decisions can rest. Scoped by a clear purpose, a written perimeter and a first sample, it remains work that is under control in both cost and time.