ORPHANWARE Why documentation comes before migration
A migration project replaces a program, but the business actually depends on behavior: how an invoice total is rounded, which customers get which discount, what happens when stock goes negative, which report the accountant reads every month. Those rules were decided years ago, often by one developer, and many of them were never written anywhere except in the code. A replacement built from interviews and memory quietly drops the rules nobody remembered to mention. The differences show up after go live, in wrong totals and missing reports, when the old system is already switched off and cannot be asked. Documenting first turns the old system into the specification for the new one, and it makes every migration quote you collect more accurate, because the vendor is pricing known work instead of guessing.
What to document
A useful pre-migration record covers six things. Each one answers a question the migration team will otherwise answer by guessing.
- Behavior inventory. Every task people actually do in the program, written as a workflow: who does it, how often, what goes in, and what comes out. Include the rare ones, such as year end, a correction, or a refund.
- Screen catalogue. A screenshot of every screen and dialog in use, with notes on what each field does and which fields are required.
- Report catalogue. A saved sample of every report and printout, with who reads it and why. Reports are where hidden calculations surface.
- Data dictionary. Every table or data file, every field, its type, and what it means in business terms, including the codes and flags whose meaning only the program knows.
- Business rules. The calculations and conditions: pricing, tax, rounding, validation, numbering, and what the program refuses to allow.
- Integrations and scheduled jobs. Every file the program imports or exports, every other system it talks to, every printer or device it drives, and every task that runs overnight or at month end.
How to capture it while the system still runs
Most of this record can be built by people who use the program, without touching any code. Sit with each regular user and record their workflows step by step. Screenshot every screen as you go. Print or save every report to a file, ideally for the same period, so the numbers can be checked against each other later. Copy the data files and note the folder they live in. Ask what happens at month end and year end, and write down the answer. Then run a few known cases through the program, such as a typical order, an edge case, and a deliberate mistake, and save exactly what comes out. Those saved inputs and outputs become test cases: the new system passes only when it produces the same results.
Where the binary fills the gaps
Observation has limits. Users know what they do, not what the program does behind the screen. A rounding rule, a discount tier that fires once a year, a field that is silently recalculated on save, or an error path nobody has triggered in a decade will not appear in interviews or screenshots. When the source code is gone, those rules still exist in one place: the compiled program. Binary recovery reads that program directly. The pipeline decompiles it, reconstructs readable source, and from that source the business rules, data structures, and file formats can be documented precisely instead of reconstructed from memory. That is the difference between a migration that copies what people remember and one that copies what the program does.
Documentation also keeps your options open
Documenting the old system is not a commitment to migrate. The same record supports every path: keeping the system running with confidence, recovering its source so it can be maintained, or replacing it on a schedule you choose. If the migration estimates come back higher than expected, you have lost nothing, and the business finally has a written description of a system it depends on every day. The developer retired guide covers securing installers, data, and credentials first, and the Visual FoxPro and Clipper guide compares keeping, recovering, and migrating for the most common legacy platforms.
Where to start this week
- Back up the program folder, its data files, and its installer, and store the copies off the machine.
- List every person who uses the program and book an hour with each to record their workflows.
- Save a sample of every report the business reads.
- Write down every file, system, and device the program touches.
- Find out whether any source code, documentation, or escrow deposit exists. The escrow guide explains what a deposit should contain.
- If the source is gone, get a verdict on whether the compiled program can be read before the migration scoping starts.
A $45 Recon Report is that verdict. It documents what the program does, its interface, and the file formats it handles, and says honestly whether a full recovery is realistic. See a sample Recon Report to judge whether it fits your migration planning, or check the directory for your platform by name.