Every migration programme begins with the same step: building an as-is picture of the system you intend to change. Historically that step takes months of specialist time — and the picture is obsolete before it is finished.
Why hand-written as-is documentation fails
Documentation written by hand is a snapshot. It is true on the day it is written and drifts out of date with every subsequent change. By the time a large programme reaches delivery, the baseline it was scoped against no longer matches the system in production. The result is scope shocks, padded estimates, and the quiet erosion of trust between the people who own the process and the people who own the code.
A baseline regenerated from the code
The alternative is to stop maintaining documentation by hand and start deriving it from the source. When the as-is picture is produced deterministically from the real code, two things change:
- It is complete — measured against the actual inventory, not against what someone remembered to write down.
- It is current — regenerated on every upload, so the marginal cost of keeping it accurate trends toward zero.
What a trustworthy baseline contains
- A quantified system: programs, interfaces, batch jobs, tables, complexity.
- Call graphs and data lineage, with every hidden dependency surfaced.
- Every statement cited back to the exact line of source it came from.
That last point is the difference between documentation that is defensible and documentation that is merely decorative. When every fact carries a citation, an auditor, an architect and an engineer can all trust the same artifact.
The takeaway
If your next migration depends on a baseline you produced by hand, you are scoping against a guess. Produce it from the code instead — and keep it current for free.