Documenting a system nobody remembers building.

The situation

A system exists, works, and is not understood. Classically that meant code inherited from people who left. Increasingly it means code produced across many agent sessions, each locally reasonable, with no one ever having reviewed the shape that resulted. Both produce the same position: you cannot safely change what you cannot describe.

Start with structure, not with reading

Reading legacy code linearly is the slowest way in, because the information you need is distributed across files and the parts that matter are not marked. Generating a diagram gives you the shape first, and then reading is targeted at the components that turned out to be central rather than at whatever file you opened first.

What it typically reveals

Two things, repeatedly. Duplicated responsibility, where the same job is done in two places by slightly different code, usually because two sessions solved the same problem independently. And a utility module that has quietly become the centre of the dependency graph, which is where every change becomes risky. Neither is visible in a file tree and both are obvious in a drawn graph.

Documentation that can be regenerated

The reason legacy systems are undocumented is not that nobody wrote documentation, it is that what was written stopped being true. Generating from code means the cost of refreshing is a command rather than an afternoon, which is the only version of this that survives contact with a busy team.

Getting oriented

Related

• Onboarding Engineers to a Codebase
  The first week is spent building a mental model that somebody already has. A diagram transfers it in an afternoon.
• Architecture Review
  Most of the effort in an architecture review goes into producing the diagrams, and most of those diagrams describe the system as remembered rather than as built.
• System Design Interview Preparation
  The diagram is the easy part. Interviews are decided by the tradeoffs you can defend when the interviewer pushes.
• Technical Design Documents
  The diagram in a design doc usually gets drawn last, badly, because everyone is tired of the document by then.