Missing documentation in legacy systems — and how we solve it

Legacy IT structures are like old buildings. They have character, a traceable origin and often surprisingly robust foundations. But they also have walls no-one dares to touch any more, cable ducts that aren't labelled and keys whose doors no-one knows. When we go into a first conversation with new clients, this is the central pain point in nine cases out of ten: documentation is missing for central components.

We want to use this post to set out our view of documentation and to show how we methodically bring order into legacy projects — without you needing to set up a six-month documentation project for it.

Why documentation is missing — and that isn't an accusation

Missing documentation is rarely the result of negligence. It's the result of pressure. Under time pressure, solutions emerge. Under cost pressure, what isn't immediately visible gets cut. Under staffing pressure, what's on fire right now gets prioritised. In all of these cases, documentation is the task that should get done tomorrow. And sometimes that tomorrow comes seven years later.

The problem only shows up when a colleague leaves, the system has to be upgraded or an external partner needs access. Suddenly it turns out no-one can fully explain the architecture, that verbal agreements were the only source of truth, and that the reason for a particular configuration has long been forgotten.

Our principle: documentation arises in the doing

We don't believe in big documentation projects that, after six months, leave behind a wiki no-one reads. We believe in documentation that comes into being in everyday operation, close to the code, close to the decisions, close to the operations. Three tools are central for this.

1. Automated documentation from the source

Many of the contents that are laboriously maintained in classic wikis already exist inside the systems themselves. Infrastructure descriptions sit in Terraform code. Database structures sit in the migration history. CMS configurations sit in Composer files and YAML setups. We use tools that automatically generate readable documentation from these sources — and re-generate it on every build.

The advantage: this documentation is always current. It isn't the last state from three years ago, it's the state from this morning. For us and for you that means no-one is left wondering “which version is actually running?” The answer is documented because it's part of the system.

2. Architecture Decision Records (ADRs)

Auto-generated documentation can say what is. It can't say why it is so. That's exactly what we use Architecture Decision Records for. An ADR is a short, standardised document that describes a concrete architectural decision: the context, the alternatives considered, the decision taken and the consequences accepted.

We keep ADRs directly in the project repository, numbered, with date and owner. If three years from now someone asks why a particular service doesn't run on Kubernetes or why we avoided a particular extension, the answer is traceable. That doesn't save time in writing — it saves time in justifying, debating and trying to repeat old mistakes.

3. Runbooks for operations

The third pillar of our documentation is runbooks. A runbook describes step by step how a recurring operational task is performed: a TYPO3 major upgrade, a database failover, a restore from backup, the onboarding of a new editor. Runbooks aren't written by people theorising, but by those who have actually performed the step.

For you that means: tasks aren't tied to individuals. If someone is unavailable, somebody else can take over cleanly. When we work on a project alongside your internal teams, runbooks become the shared place for operational knowledge.

How we work in existing systems

When we take over a legacy system, we don't start with the ambition of reconstructing the full history. We start with a stocktake: what's critical, what's running, what's a risk? On that basis we prioritise documentation work so that we shed light first where the risk is greatest — usually at interfaces, at security-relevant configurations and at processes only one person understands.

In parallel we introduce our three tools: automated documentation, ADRs for new decisions, runbooks for the most important operating procedures. Older decisions whose context has been lost we document pragmatically, with the note that the original reason can no longer be ascertained. That sounds banal but it matters: honesty about not-knowing is part of serious documentation.

What you get out of it

Planning certainty. Upgrades, migrations and staff changes become predictable, because knowledge no longer sits only in heads.

Faster onboarding. New colleagues — internally and with us — find their way around documented systems in weeks, not months.

Better security. Documentation is the precondition for clean audits and for fast responses to CVEs.

Less dependence. You're no longer dependent on a single person or a single supplier just because that's the only place the knowledge lives.