Nobody reads your data docs. Write them anyway.

For my first year working with data teams I believed documentation was theater. You write careful column descriptions, you maintain lineage, and then you watch people DM you the exact question the docs answer. The evidence seemed conclusive.

Then I spent a stretch at a financial firm doing the unglamorous thing properly — documenting lineage, business definitions, and KPI logic for the warehouse, then running short training sessions on how to self-serve — and analytics self-service went up something like 60% within six months. My DM volume fell off a cliff. So the docs-are-theater theory needed revising.

Here’s the revision. Nobody reads documentation the way you imagine, front to back, learning proactively. Docs get read at exactly one moment: when a specific person has a specific question and believes an answer exists somewhere findable. Documentation fails not because people won’t read but because at the moment of need, the doc isn’t where they’re looking, or doesn’t answer in their vocabulary, or contradicts another doc and forfeits all trust.

Which reframes the writing completely. The job isn’t coverage, it’s ambush: be present at the moment of need. That means definitions living where the data lives (column descriptions in the warehouse and BI tool, not a wiki nobody’s opened since onboarding). It means writing entries as answers to real questions, and the trick I lean on hardest: every time someone DMs me a question, the answer gets written into the docs before I reply, and the reply is a link. Rude? Slightly. Effective? The question stops recurring, permanently, and the docs grow exactly where demand exists instead of where I guessed it would.

It also means deleting stale docs with prejudice. One wrong definition costs more trust than ten missing ones. People forgive absence. They do not forgive being burned.

And the payoff compounds in a way that’s easy to miss: every question the docs absorb is an interruption that never reaches an engineer. The 60% self-service jump was really a story about reclaimed focus, mine included.

Lineage and definitions feel like chores because the beneficiary is a stranger in the future. Write for that stranger. She’s usually you, eight months out, having completely forgotten why revenue excludes channel partners.