How do you document a COBOL system nobody fully understands?
The short answer
Start from the code, not from interviews. Parse every program, copybook and job into facts that each point at a file and line, link those facts across artifacts into one map, and record what cannot be resolved as a list of gaps instead of guessing. Then have the people who know the system confirm or correct the map, and keep their corrections where the next round of documentation cannot overwrite them.
By Nisius · Updated
Why do the usual approaches fall short?
Wiki pages and spreadsheets start going stale the day they are written, because the code keeps changing and nobody is assigned to update them. Interviews capture what one person remembers, which is valuable but is not the same as what the code does. Reading programs one at a time explains each program and hides the system: the jobs, datasets and tables that connect them are exactly what a reader loses track of.
What does a reliable approach look like?
- Inventory everything the system is made of: COBOL programs, copybooks, JCL and procedures, DB2 DDL, and CICS definitions if the flow is online. A call to a program you do not have is itself something to document.
- Extract facts deterministically: calls and performs, files and the datasets bound to them in JCL, SQL against tables, CICS commands, and the IF and EVALUATE statements that route data. Each fact should record the file and line range it came from, so anyone can check it.
- Link facts across artifacts: a job step to the program it runs, a program's file to the dataset its job binds, a dataset one job writes to the jobs that read it. This is where the system becomes visible.
- Record what you cannot see: dynamic calls whose target is decided at run time, missing copybooks, datasets nobody writes. Rank them by how central the affected part is and ask for the artifacts that would close them.
- Have your experts review the result: confirm, reject or correct facts, and add what the code cannot show, such as manual steps, owners and schedules.
- Keep it current: re-run the extraction when the code changes, and keep expert corrections attached to the things they describe rather than to a document.
Where should you start?
With one flow, not the whole estate: the one your team can least afford to lose, such as nightly claims adjudication or month-end close, and three to five questions about it that are hard to answer today. A complete, checked map of one flow is worth more than a partial map of everything, and it shows quickly whether the approach works on your code.
How Telikos does it
Telikos does this as a read-only appliance inside your network. Deterministic parsers for COBOL, JCL and procedures, copybooks and DB2 SQL record facts with their file, line range and content hash; a resolver links them across artifacts and records unknowns; your experts confirm or correct the graph, and their corrections persist across re-ingestion.
You then ask questions in plain language, and every statement in the answer cites the lines it came from.
Related questions
Do we need the original developers to document a COBOL system?
No, but you need someone who knows the system to review what is extracted. The structure can be recovered from the code; the reasons behind it, manual steps and schedules usually have to come from people.
Can documentation be generated automatically from COBOL?
The structural part can: programs, calls, files, datasets, jobs and tables can be extracted deterministically with their source locations. Explanations of business rules can be drafted by a model, but they should cite the code and be reviewed by an expert before anyone relies on them.