Legacy systems are rarely documented well. The people who built them may have moved on, behaviour has been patched over years, and important details live only in configuration files or in someone's memory. Migrating such a system without first documenting it is a common cause of surprises: a forgotten nightly job, an undocumented file export that another department depends on, a business rule hidden in a stored procedure.
Documentation before migration does not have to be exhaustive. It should be accurate enough to plan the work, estimate risk and test the result.
Start with a component inventory
List every part of the system: applications, services, databases, file shares, scheduled jobs, scripts, queues and third-party services. For each item, record what it does, where it runs, the technology and version, who owns it and how it is deployed. A simple spreadsheet is enough at first.
Build a dependency map
Show how components connect to each other and to systems outside the boundary: which service calls which, which database tables are read or written by which processes, which files are exchanged and in what direction. Diagrams help, but the underlying list of connections, with protocols and frequencies, is what you will use for planning.
Sources of dependency information include network connection logs, database access logs, firewall rules, configuration files and integration settings. Observing the running system often reveals connections nobody remembered.
Find the hidden work
Legacy environments often contain activity that is not visible in the main application:
- scheduled tasks and cron jobs;
- database triggers, stored procedures and views used by reports;
- scripts run manually at month-end or year-end;
- files dropped to or collected from shared folders or SFTP servers;
- emails sent automatically to people or other systems.
Ask operators and users about periodic tasks, and review at least a full business cycle of logs if possible, because some processes run only quarterly or annually.
Document data
For each data store, record the main entities, approximate volumes, growth, retention rules and sensitive fields. Note data quality issues you discover, such as duplicate records or inconsistent codes, because they will affect migration. Identify which system is the source of truth for each type of data.
Capture business rules
Business rules, such as how discounts are calculated or when an account is flagged, are often embedded in code. Record the important ones in plain language with examples. Characterization tests, which capture current outputs for known inputs, are a practical way to preserve this behaviour and verify it after migration.
Write operational runbooks
A runbook describes how to operate the system: starting and stopping it, deploying changes, restoring from backup, handling common errors and who to contact. Runbooks are valuable during the migration, when both the old and new systems may run at the same time, and they reveal operational knowledge that the new system must replicate.
Interview the people who know
Long-serving developers, administrators and power users know things no document contains. Short, structured interviews with a list of questions, such as "what breaks most often?" and "what do you do at the end of each month?", capture this knowledge efficiently. Record the answers in the shared documentation, not just in meeting notes.
Keep documentation alive
Store everything in one place that the whole migration team can edit, such as a wiki or a repository. Date each document and name an owner. Update the inventory and dependency map as you learn more; they will change during the project.
Key takeaways
- Inventory components and map dependencies, using logs and configuration to verify them.
- Look for hidden jobs, scripts, triggers and file exchanges across a full business cycle.
- Document data, business rules and operations, not only architecture.
- Capture knowledge from people and keep the documentation current throughout the project.