Documentation that stays true

You will be asked why this attempt at documentation will work when the last three did not. Here is the answer, and it does not require anybody to be more committed than they were last time.

"The last three attempts asked people to update a second place. This one has no second place." When the description of a column sits beside the definition of that column, renaming the column and updating its description are the same edit, reviewed by the same person, in the same change. There is no separate task to deprioritise, because there is no separate task.

Then add the part that closes it: and the dependency map is not drawn at all. It is read out of the project's own build output. This course's project has a lineage graph of 32 nodes and 47 edges, and nobody maintains it. It cannot be out of date, because if the dependencies it describes were wrong, the build that produced it would not have worked.

Almost every organisation has a data-flow diagram somebody made once. It is usually beautiful, usually on a wall or in a shared drive, and usually wrong in at least two places that matter. It is wrong because it was a snapshot of an estate that kept moving, and nothing about the estate moving updates the picture.

A derived graph is a categorically different object. Because every model names its inputs in the code rather than pointing at a table directly, the tool can read the whole dependency structure out of the code itself. That has three consequences a leader should care about:

• It is accurate by construction. Not maintained accurately: incapable of being inaccurate about the dependencies that exist in the code. Session b4 of the builder track explores the real graph node by node.
• It answers "what breaks if we change this" before the change. Which converts a rename from a three-week discovery process into a question with an answer, and is why teams with derived lineage still rename things.
• It costs nothing per model. A drawn diagram gets more expensive as the estate grows, which is precisely why it stops being updated at the size where it would start being useful.

This is the single strongest line in a business case, and it is the one leaders most often leave out because it sounds like a technical detail. It is not. It is the difference between an estate you can change and one you can only add to.

A missing document is a known gap. Somebody asks a question, nobody has an answer, and the cost is a conversation. That is a cheap failure and it is self-announcing.

A wrong document is worse in a specific way: it gets quoted. An analyst reads that a column excludes cancelled orders, builds a report on that basis, and the report is wrong in a manner nobody can trace, because the reasoning was sound and the input was false. Six months later two teams present different numbers and the reconciliation takes a week, and the root cause is a page that was accurate when it was written.

This is why "we should just write better documentation" is not a plan. Better writing produces the same decay on a slightly slower schedule, and the failure mode is unchanged. The only fix that changes the failure mode is removing the second place where the text lives, so that being wrong requires the code to be wrong too.

This proposal will arrive, and it will be well intentioned. A separate catalogue tool, populated by the team, describing all the tables. It sounds like more than generated documentation because it covers more surface area.

The question to ask is not whether the catalogue is good. It is: what makes an entry in it wrong loudly rather than quietly? If the answer is a person remembering to update it, you have rebuilt the wiki with a nicer interface and the same failure mode, and you now have three places where a column's meaning lives instead of two.

There is a legitimate version of this. A catalogue that reads its descriptions and lineage from the transformation project rather than storing its own is genuinely useful, because it adds discovery and search across systems on top of a source of truth that stays true. The distinction is direction: does the catalogue pull from the code, or does a human push into the catalogue? Pull is an amplifier. Push is a wiki.

Here is a benefit that rarely makes the business case and is worth knowing about. When descriptions live in the code, they inherit the code's history. You can see when a description was last touched, by whom, and in the same change as what.

That gives you something no wiki gives you: a way to find documentation that is probably wrong. If a model's logic was edited four times this year and its description has not been touched in eighteen months, that is a specific, findable, prioritisable piece of staleness. On a wiki, every page looks equally current, which is why nobody can triage them and why the annual documentation clean-up never happens twice.

It is a small mechanism and it changes documentation from a monolith you cannot maintain into a list you can work through. Ask your team whether they can produce that list. If the answer is yes, they have already built the thing this session is asking for.

Generated documentation describes the estate as it is. It has no access to the reasoning that produced it, because the reasoning was never written into the code and mostly could not be.

That material is real and it is what people actually need in the hard moments: why the fact table is at order-line grain rather than order grain, why the revenue definition excludes what it excludes, which compromise was accepted under deadline and is still outstanding, and what was tried in the first attempt and abandoned. None of it is derivable. All of it needs prose that somebody writes and somebody owns.

The sibling course, learn-data-modeling, keeps exactly this in a contract file alongside the model: the decisions, the grain justification, the known compromises, and the name against each. That is where it belongs. Not in the wiki, because it has the same decay problem, and not in generated docs, because it cannot be generated. Beside the model, written by hand, with an owner and a date.

The derived graph knows about every dependency expressed inside the transformation project. It knows nothing about anything outside it, and the things outside it are the ones your stakeholders see.

The practical effect: a change can be entirely safe according to the lineage and still break the report the executive committee reads on Monday, because that report queries a mart directly and the graph has never heard of it. Nobody is at fault. The information genuinely was not there.

The mechanism for closing that gap is a declared consumer, which dbt calls an exposure: a dashboard, an export or a sync recorded deliberately in the project so it appears in the graph and in the impact analysis alongside everything else. It is a small amount of work with an unusual property for documentation, in that it makes something previously invisible show up in the blast radius automatically from then on.

As a leader you do not need the mechanism. You need to ask one question and then insist on the answer being written down somewhere the graph can see: which dashboards, exports and syncs read directly from our models? The builder track wires this up; your job is to make sure the list exists.

The prompt. "Open our data documentation. Take the five most-viewed pages. For each one, read out the last edit date, and then pick one factual claim on the page and check it against the warehouse right now."

What a good answer sounds like. Discomfort, quickly followed by specifics: "this one says the table is refreshed hourly and it has been daily since March." That is the session's argument demonstrated on your own material in under six minutes, and it is far more persuasive than anything on these slides because your team found it themselves.

The failure mode to listen for. "The dates are recent, so we are fine." Recent edit dates measure attention, not accuracy, and pages get touched for formatting. Insist on the factual check, on the highest-traffic page, in the room. The most-quoted page being wrong is the finding that changes the next planning cycle.

The prompt. "List everything we currently maintain by hand that describes our data: the lineage diagram, the column glossary, the metric definitions document, the dashboard inventory, all of it. Now sort each one into three piles. Could be generated today. Cannot be generated, and needs a named owner. Should not exist at all."

What a good answer sounds like. The generated pile is larger than anyone expected, and the third pile is not empty. Something gets moved to "should not exist" because it duplicates another document, and somebody says so out loud. Ideal output is two or three items you stop maintaining this month, and one item that moves from nobody to a named owner.

The failure mode to listen for. Everything landing in "cannot be generated" with justifications about how the organisation is special. Some of that is real, most of it is attachment to work already done. Test each claim against the three artifacts in Part 2: lineage, column descriptions, test lists. If a team insists those three cannot be generated for them, the reason is usually that the models are not in a transformation tool yet, which is session a4's question and not a documentation question at all.

The prompt. "Pick our three most-used tables. Now list, on the board, every single thing that reads them directly and is not one of our own models: dashboards, scheduled exports, the sync into the CRM, that spreadsheet finance refreshes, the API somebody built. Then tell me where that list is currently written down."

What a good answer sounds like. A longer list than anyone predicted, with two or three items that surprise the room, and an honest "nowhere" to the second half of the question. That combination is exactly what exposures exist for, and you have now produced the input list in ten minutes without any tooling.

The failure mode to listen for. A short, confident list of the official dashboards only. Ask specifically about the unofficial ones: the export somebody set up for a board pack, the sync into a sales tool, the direct connection from a spreadsheet. Those are precisely the consumers that break loudly and are absent from every diagram, and the person who knows about them is usually not in the room, which is itself worth noticing.