Separate what is known from what still needs verification

Documentation for a legacy system is rarely a single, tidy folder. It is usually scattered across wikis, shared drives, email threads, ticketing systems and the heads of people who have worked there for years. When you are planning a takeover, modernisation or migration, the first job is to find out what actually exists, what is current and what the gaps mean for your project.

There are several distinct categories of documentation you should expect to encounter, even if some turn out to be missing:

  • Architecture and design documents — high-level diagrams showing how the system fits together, what services or modules exist and how data flows between them.
  • Process and workflow documentation — descriptions of the business processes the system supports, including decision points, approvals and exceptions.
  • Data dictionaries and schema documentation — definitions of tables, fields, relationships and what each data element means in business terms.
  • API and integration documentation — details of endpoints, authentication methods, data formats and any third-party systems the application connects to.
  • Deployment and infrastructure documentation — how the system is hosted, what environments exist, how releases are carried out and what dependencies the servers require.
  • User guides and operational runbooks — instructions for day-to-day users and for the people who keep the system running, including common failure scenarios and recovery steps.

The critical distinction is not between "documentation present" and "documentation absent". It is between documentation that reflects the system as it runs today and documentation that describes an earlier version, a planned version that was never finished or a theoretical design that was simplified during build. A 200-page technical specification is worth less than a one-page diagram that accurately matches the live environment.

Assessing documentation is therefore a matching exercise: you are comparing what the documents say against what the system actually does. That comparison is what tells you where the real risks lie.

Vendor takeover

If you are taking over a system from another supplier, documentation is often your only starting point. Before accepting a handover, request a full inventory of available materials and categorise them against the list above. Then pick a small number of critical processes — perhaps the most complex workflow or the most frequently used integration — and walk through them using the documentation alone. If the documents do not get you through the process without asking the outgoing team questions, you have identified a dependency that needs to be resolved before the handover completes.

Modernisation planning

Before deciding whether to rebuild, refactor or replace, you need to understand what the current system does. Documentation gaps here directly inflate discovery costs. If data dictionaries are missing, someone will have to reverse-engineer the database schema and validate the findings with business users. If integration details are absent, each connection will need probing and testing. The documentation assessment gives you a realistic view of how much unknown ground exists before you commit to a modernisation route.

Compliance and audit preparation

Regulatory requirements often demand that you can explain how data is processed, stored and retained. Legacy systems built before current regulations were in place frequently lack this kind of documentation. Assessing what exists allows you to identify which processes are undocumented and therefore represent a compliance gap that will need addressing regardless of any technical changes you plan.

Onboarding a new internal team

When a system has been maintained by a small group for a long time, much of the knowledge is implicit. If those people leave, the documentation is all that remains. Assessing it in advance tells you how long onboarding will realistically take and whether you need to budget for a knowledge-capture phase before the current custodians move on.

Verifying accuracy

Regardless of the scenario, the most reliable verification method is to pick a real transaction or workflow in the live system and trace it through the documentation. If the documents say that step four sends an email to the account manager, check whether that is what actually happens. If the data dictionary says a field stores a date in a particular format, query the database and confirm. This spot-checking approach is faster than reading everything and far more revealing than assuming completeness based on folder size.

Where the work usually goes wrong

  • Counting pages rather than checking relevance. A large volume of documentation can create a false sense of security. Fifty pages of outdated design documents are less useful than a single accurate runbook.
  • Confusing user manuals with system documentation. A well-written guide for end users tells you what the system does from the outside. It does not explain the data model, the integration points or the deployment process.
  • Assuming the development team's documentation is sufficient for operations. Technical docs written for developers often omit the operational context: how to recognise when something is wrong, how to restart services, what to check after a deployment.
  • Accepting documentation without version dates. Any document without a clear last-modified date or version number should be treated as unverified. Ask when it was last updated and what changed since then.
  • Ignoring informal documentation. Confluence pages, Slack threads, Jira ticket descriptions and even sticky-note photographs can contain information that never made it into formal documents. These sources are messy but sometimes the only record of a critical workaround or business rule.

What this work cannot prove on its own

Documentation assessment has hard boundaries. It cannot tell you about vulnerabilities in the code itself — that requires a separate security review. It cannot reveal whether the codebase is well-structured or fragile — that requires a codebase assessment. And it cannot substitute for talking to the people who use and maintain the system daily. Documentation is one input into your overall understanding, not a replacement for the others.

There is also a practical limit to how much accuracy you can verify without access to the live system. If you are assessing documentation during a procurement process and do not yet have system access, you can only flag inconsistencies and unknowns for later investigation, not resolve them on the spot.

Checks to complete before relying on the result

  • Inventory completeness. Do you have materials covering all six categories listed above, or are there entire areas with nothing?
  • Version currency. Do the documents have dates, and do those dates align with the last known release or change to the system?
  • Data dictionary coverage. Are all major tables and fields defined, or are there undocumented columns that appear to hold business-critical information?
  • Integration inventory. Is there a list of every external system the application communicates with, including the direction of data flow and the frequency?
  • Environment documentation. Are all environments (development, staging, production) described, including any differences between them?
  • Known issues and workarounds. Is there a record of things that are broken, bypassed or running on temporary fixes? These are often the highest-risk areas during any change.
  • Access and credentials. Is there a clear record of who has access to what, where credentials are stored and how they are rotated? Even if this is a security matter, the absence of any record is a documentation gap that will affect your handover.

Record the current state and unresolved risks

The output of a documentation assessment should not be a pass or fail grade. It should be a structured list of what exists, what is missing, what is potentially outdated and what you were unable to verify. That list then feeds directly into your planning for discovery, risk allocation in contracts and the timeline for whatever comes next — whether that is a takeover, a modernisation project or a compliance remediation exercise.