Onboarding docs that regenerate themselves

Arriving at an unfamiliar data store is a particular kind of stuck. There are a few hundred tables. The names are abbreviations somebody understood in 2014. The people who would know are busy, and the documentation, if it exists, was written once and has been drifting ever since.

So you click through a schema browser one table at a time, building a mental model you will not write down, which is how the next person ends up doing exactly the same thing.

It walks every table, records the row count, pulls a small sample of rows, and asks a model for a one-line description based on the name and that sample. The result is a single Markdown file: one row per table, with size and a plain sentence. A companion does the same for object storage containers.

Sampling rather than reading is the whole trick. A handful of rows is enough for a model to tell you that a table holds purchase orders with status and totals, and it means the tool takes about a minute regardless of how large the database is.

Documentation rots because writing it is a separate act from the thing it describes, so the two drift from the moment the document is saved. The usual response is to demand more discipline, which works for a quarter.

The alternative is to make the document cheap enough to throw away. If a map can be regenerated from the live system in a minute, staleness stops being a problem worth managing — you never repair it, you re-run it. That changes what documentation is for: not a record to be maintained, but a view to be taken.

The honest limitation is that the descriptions are inferred from a name and a sample, so they are a good map and a bad citation. It will tell you which three tables to look at, and it should never be the thing you trust for what a column means. That is a fair trade for going from nothing to oriented in a minute, as long as the document says so.