The Documentation Gap

How to rebuild reliable knowledge of a legacy system without its source code or its original authors

The people who built your core system have gone. The documentation is either missing or quietly wrong. Nobody can say with confidence which parts of the system are still in use. This guide shows why that knowledge is recoverable, and how to recover it from the one source that never goes out of date: the running system itself.

Why documentation drifts for structural reasons, and why more discipline has never fixed it.
How three layers of evidence in a user session rebuild processes, rules and roles.
What behavioural documentation can recover, and the three things it cannot.

Get the free e-book

See what's inside

Nobody left can describe the system, and it runs the business anyway

This is the normal condition of enterprise IT, not an unfortunate exception. A business-critical application built ten or fifteen years ago. A specification that stopped being updated somewhere around the third release. A handful of people who know how it really works, one of whom is retiring.

The cost is rarely visible as a line item, which is why it rarely gets funded. It shows up instead as friction in the situations where missing documentation is most costly.

You will recognise this if

Every change request comes back with a padded estimate because nobody can predict the impact

During an incident, the question of what else is affected is answered from memory

An auditor has asked you to demonstrate what the system does, not to describe it

A migration is on the table and nobody can say what would actually have to be rebuilt

Most guides tell you to write better documentation next time. This one does not.

The market gives you two answers to a missing specification. Read the code, or run workshops with whoever is left. Both answer a real question, and neither answers this one.

Code tells you what the system can do. It treats a feature built for a client who left in 2019 as being exactly as real as the screen your operations team opens four hundred times a day. Workshops tell you what people can describe, which is the main path without the exceptions, because the exceptions became automatic years ago.

There is a third source, and it does not drift. The running system is the most current specification of itself, and the way users behave in it is the interface through which that specification can be read.

Three ways to find out what a legacy system does

Each answers a real question. The differences decide which one fits the situation you are actually in.

Three additional rows, including one showing which approach stays current as the system changes, are included in Chapter 3 of the e-book.

Get the free e-book

Including the part most vendors leave out

An approach that claims to recover everything should not be trusted with anything. Chapter 4 of the e-book states the limits as plainly as the capabilities, because an enterprise architect is going to look for them anyway.

Three things behavioural documentation cannot recover:

#1

Why a rule was introduced

Observation establishes that a rule exists and what it does, not which regulation or commercial agreement it encodes.

#2

Anything that never surfaces in the interface

Including batch jobs and system-to-system integrations.

#3

Anything that does not happen during the observation window

Which is why the window is planned against your business calendar.

The e-book explains what to do about each of them.

What is inside

01 Why documentation drifts. The four mechanisms, and why the bottleneck in modernisation moved from building to specifying

02 What the gap actually costs you. Five recurring situations where the cost is paid and attributed to something else

03 The system is the specification. Three layers of evidence in a user session, and how they compare to reading the code

04 What can be reconstructed, and what cannot. The full catalogue, with the limits stated

05 Non-invasive by design. How observation works, where the data sits, and the six questions your security review will ask

06 The step that pays off under every path. Seven modernisation paths, one shared prerequisite

07 What the first two weeks look like. The four steps from installation to a documented system

08 Where to start. Four criteria for choosing the first system to observe

Written for the people who have to make the decision

IT directors

You are being asked to commit to a modernisation path for a system nobody can fully describe. The guide gives you the input that every path requires, and the argument for getting it first.

Enterprise architects

You need a method with stated limits, not a promise. Chapters 3 and 4 are written to be read sceptically.

Heads of ICT risk and compliance

You need to demonstrate what a system does rather than assert it. Chapter 5 covers what is captured, where it is stored and who controls it.

Where OmniSense fits

The e-book is about a method. OmniSense is how Pretius applies it. A lightweight component is installed alongside your application, records real user sessions and turns them into structured documentation of the system, without access to your source code.

Installation carries no upfront cost beyond compute resources

First documentation output typically within one to two weeks

Captured data stays within your own infrastructure

Sovereign, custody and hybrid deployment models, with support for local models

Get the e-book

Leave your work email and we'll send the PDF straight to your inbox.

FAQ

Yes. Documentation can be generated from how the system is actually used rather than from how it was built. The e-book explains which artefacts this produces, including process diagrams, business rules as they are actually enforced, role permissions and a map of which modules are still in use.

Code analysis describes what the system is capable of doing. Behavioral observation describes what it does. When the objective is to establish scope, the difference between four hundred screens that exist and forty that carry the business is the whole exercise.

No. The collection component runs alongside the application, does not modify source code or business logic and can be removed without a restart. Where requirements are higher, it can run in a dedicated environment equivalent to production.

Within your own infrastructure. Sovereign deployment keeps both collection and processing on your network, and in the custody model Pretius has no direct access to the environment at all.

The first documentation output is typically available within one to two weeks of installation, and installation carries no upfront cost beyond compute resources.

It cannot recover why a rule was introduced, it cannot see processes that never surface in the interface, and it cannot capture anything that does not happen during the observation window. Chapter 4 covers all three and what to do about them.

Looking for a software development company?

Work with a team that already helped dozens of market leaders. Book a discovery call to see:

How our products work
How you can save time & costs
How we’re different from another solutions

Michał Lipiński

Account Manager

+48 666 038 971

mlipinski@pretius.com

Book a meeting

The Documentation Gap

How to rebuild reliable knowledge of a legacy system without its source code or its original authors

Nobody left can describe the system, and it runs the business anyway

You will recognise this if

Most guides tell you to write better documentation next time. This one does not.

The market gives you two answers to a missing specification. Read the code, or run workshops with whoever is left. Both answer a real question, and neither answers this one.

Three ways to find out what a legacy system does

Each answers a real question. The differences decide which one fits the situation you are actually in.

Including the part most vendors leave out

An approach that claims to recover everything should not be trusted with anything. Chapter 4 of the e-book states the limits as plainly as the capabilities, because an enterprise architect is going to look for them anyway.

Three things behavioural documentation cannot recover:

#1

Why a rule was introduced

#2

Anything that never surfaces in the interface

#3

Anything that does not happen during the observation window

What is inside

01

Why documentation drifts. The four mechanisms, and why the bottleneck in modernisation moved from building to specifying

02

What the gap actually costs you. Five recurring situations where the cost is paid and attributed to something else

03

The system is the specification. Three layers of evidence in a user session, and how they compare to reading the code

04

What can be reconstructed, and what cannot. The full catalogue, with the limits stated

05

Non-invasive by design. How observation works, where the data sits, and the six questions your security review will ask

06

The step that pays off under every path. Seven modernisation paths, one shared prerequisite

07

What the first two weeks look like. The four steps from installation to a documented system

08

Where to start. Four criteria for choosing the first system to observe

Written for the people who have to make the decision

IT directors

Enterprise architects

Heads of ICT risk and compliance

Where OmniSense fits

The e-book is about a method. OmniSense is how Pretius applies it. A lightweight component is installed alongside your application, records real user sessions and turns them into structured documentation of the system, without access to your source code.

Installation carries no upfront cost beyond compute resources

First documentation output typically within one to two weeks

Captured data stays within your own infrastructure

Sovereign, custody and hybrid deployment models, with support for local models

Get the e-book

Leave your work email and we'll send the PDF straight to your inbox.

FAQ

Can you document a legacy system without the source code?

How is this different from static code analysis?

Does this require changes to our production system?

Where is the captured data stored?

How long does it take to see something?

What can this approach not do?

Looking for a software development company?

Work with a team that already helped dozens of market leaders. Book a discovery call to see:

Michał Lipiński

Account Manager

We keep your data safe: ISO certified

Drop us a line at

Want to work with us?

What we do

How we do it

Products

Sitemap