Your data platform shouldn’t need you in the room

If a task is only safe when you do it, it isn’t safe. It’s a single point of failure that happens to be employed right now.

TL;DR — the short version

Do any of these sound familiar? Every question about the numbers routes to the same person. A change everyone agrees on waits a week because the one who knows is out. A number moves, and “who changed this?” gets a shrug.

There’s a version of a data platform engagement that looks like a total success and leaves the client worse off. Every model ships. Every dashboard is fast. Every number reconciles. And when the person who built it leaves, the whole thing quietly freezes in place — because nobody else knows which table is canonical, or what happens if they change the thing that looks safe to change.

That’s not a platform. That’s a dependency with good uptime. So on a recent client engagement, a real share of the work wasn’t building — it was handover:

• Teaching Git to the analysts and ops folks who operate the platform — the four commands they’ll use, not the theory.
• Writing the references so “which table is the real one” stops being a question that routes to a person.
• Runbooks for the operations that scare people.
• Making the rules stick — not by documenting them, but by explaining what the shortcut costs.

Here’s what handing a revenue data platform to the team that has to run it actually took — including the part that gets oversold. ↓

Teaching Git to people who aren’t engineers

Analysts and ops folks, learning branches, pull requests, and review. Not to turn them into software engineers — because “who changed this, when, and why” is otherwise unanswerable, and in a revenue data platform that question comes up constantly. Usually at the worst possible moment, when a number moved and nobody can say what moved it.

The framing that made it land, after a few that didn’t: a pull request is not bureaucracy — it’s the only version of your change history that survives turnover. Nobody wants process for its own sake. Everybody wants to not be blamed for a change they didn’t make. Version control is how you get that.

What helped, concretely:

• Teach the four commands they’ll use, not the model. Branch, commit, push, open a PR. The internals of the object store are fascinating and irrelevant to someone whose job is pipeline coverage.
• Make the first PR a documentation change. Low stakes, no chance of breaking anything, and they get the full loop — branch, change, review, merge — before they touch a model.
• Review generously in public. The first few reviews decide whether people believe review is help or judgement. That impression is very hard to change later.

Stop making “which table is the real one” a question

Most of the friction wasn’t technical. The answers lived in people’s heads, so every question routed to whoever had been there longest. The fix is unglamorous: write the references. A logic reference for each major domain — what the funnel stages mean, how activity gets categorized and attributed. Lineage documentation for the datasets that feed reporting. Analyst guides for the surfaces people actually operate.

The test of whether these are any good is not completeness. It’s whether a new person can answer their own question at 9pm without messaging anybody. That is the whole standard.

Runbooks for the operations that scare people

Renaming a model that eleven things depend on. Cutting a report over to a new source. Re-syncing a spreadsheet-backed seed without stranding history. These are the tasks that get deferred indefinitely because they feel dangerous — and they feel dangerous because they are, until somebody writes down the order of operations, the verification step after each one, and the rollback.

Once written, they stop being scary and become boring, which is the goal. Boring operations get done. Scary operations become tech debt with a story attached.

The honest part: protocols don’t stick because they’re documented

You can write the rule, socialize the rule, put it in the onboarding doc, and pin it in the channel. People will still bypass the governed layer, because reaching around it is faster in the moment and the cost is invisible and deferred. Documentation does not create adherence. It only makes adherence possible.

What creates adherence is a consequence people can see. Somebody takes the shortcut, a wrong number ends up in front of leadership, and then — this is the important bit — the team gets a clear, blameless explanation of the mechanism. Not “follow the protocol.” Rather: here is the shortcut, here is precisely how it dropped a third of the population, here is why nothing alerted, here is what it would have cost if it had run one more week.

Explaining the cost of the shortcut beats restating the rule, every time. People comply with rules they understand the physics of. They route around rules that feel like someone else’s preference.

The bit I didn’t expect: documentation for two audiences

Late in the engagement, the guidance files I was writing picked up a second reader. The same file that tells a new analyst which models are canonical, how to join on stable IDs, and what the protocol is for touching production — that file is also what an AI coding agent loads when it opens the repository. The conventions that onboard a human are the constraints that keep an agent inside the lines. One artifact, two audiences.

That changed how I write them. Rules stated as prohibited actions rather than gentle guidance, because agents read gentle guidance as negotiable — and so, frankly, do people under deadline. And a reason alongside every rule, because a reader who understands why applies it correctly to the case you didn’t anticipate. That’s true of the agent as much as the analyst.

It’s a useful convergence: every hour spent making a codebase legible to a new team member now also makes it safer for the agents that team is about to point at it.

What good handover actually looks like

Not a wiki page. Four things:

1. Canonical references for each domain — so questions resolve to a document, not a person.
2. Runbooks for every operation that would otherwise wait for the expert.
3. Working fluency in the tools of record — version control, review, the deployment path — for the people who’ll operate it, non-engineers included.
4. A shared understanding of why the protocols exist, built from real consequences rather than assertions.

Get those four and the platform is an asset: it can be operated, extended, and trusted by people who weren’t there when it was built. Skip them and you’ve delivered something impressive that starts decaying the day you leave.