The person who understood the application has left. The repository exists, but nobody is certain which branch is deployed, how the nightly job starts or why a particular customer receives a different calculation.
Documenting legacy software in this situation is an evidence-recovery exercise. Begin with the ability to operate and explain the system, then deepen the knowledge around the capability you need to change. A large architecture document is not the first requirement.
Establish what is actually running
Identify environments, deployed artifacts, source revisions, configuration locations and scheduled tasks. Record what is confirmed and what remains an assumption.
Compare deployment records with the repository. If the running version cannot be matched confidently to source, investigate that gap before promising a straightforward code change.
Locate installation packages and licence arrangements. Knowing the source code does not guarantee the organization can recreate the environment it depends on.
Secure operational continuity
Find the authorized owners of credentials, backups, certificates, domains and supplier accounts. Use normal access-management procedures rather than copying secrets into a documentation file.
Document how the application starts, stops, deploys and restores. Test those procedures in an appropriate environment and record the observed results.
An illustrative application may have a reliable backup job but depend on a manually installed driver for restoration. That dependency belongs in the runbook before the next incident exposes it.
Interview the people who handle exceptions
Operators, support staff and long-serving users may know behaviors that developers never documented. Ask them to demonstrate failed transactions, corrections and periodic work.
Use real questions: “What do you do when this batch is late?” or “Which records need a manual adjustment?” Record the reason and the evidence behind each answer.
Avoid treating every workaround as a requirement. Some should be removed, but first understand the function they perform and the consequence of changing it.
Build a small set of living documents
| Document | Purpose |
|---|---|
| System overview | Business purpose, users, environments and owners |
| Dependency map | Applications, jobs, files and external consumers |
| Workflow catalogue | Critical journeys and exception handling |
| Rule register | Decisions, examples and approval owners |
| Operations runbook | Deployment, monitoring, recovery and escalation |
| Unknowns log | Gaps, impact, owner and next investigation |
Keep these artifacts close to the delivery workflow and assign owners. A shared document without maintenance responsibility can become another source of misleading assumptions.
Trace one capability end to end
Choose a critical workflow and follow it through code, database operations, configuration and downstream outputs. Compare the observed path with user explanations.
Martin Fowler's legacy seam discussion describes boundaries useful for testing and observation. Finding such a boundary can help the team inspect behavior without understanding the entire application first.
Our business rules guide provides a structure for turning those observations into accepted requirements.
Convert discovery into reproducible evidence
Capture representative test cases and expected outcomes. Record how to build a controlled environment and repeat the workflow.
Where automated checks are practical, preserve them alongside the code. For manual investigations, record the dataset, steps and observations so another person can verify the conclusion.
Label confidence. “Confirmed by a production trace and accepted example” means something different from “inferred from a procedure name.” Keeping that distinction visible prevents guesses from hardening into specifications.
Reduce dependence on the next specialist
Have a second person follow the runbook and explain the critical workflow. Use the gaps they find to improve the documentation.
Include handover and shared access in any external engagement. The goal is an organization that can support and change the application, not a new individual holding the same private knowledge.
Tranz Technologies' software modernization service can help recover operational and application knowledge before implementation. Start with the workflow or recovery task whose uncertainty creates the greatest immediate constraint.
Talk through your software challenge.
Share your existing system, the constraints and what needs to change.
Discuss your project ↗