Show the Draft Data Model to Its Users Before You Build

Data engineers often finish a table before anyone who will use it has seen it. A pipeline runs cleanly, tests pass, row counts look right, and only then does an analyst open the result and ask why a column means something different from what the report needs. This explainer covers a simple idea: show a half-built data model to a downstream reader early, with a clear request, so that misunderstandings surface while changing the design is a matter of editing a query rather than backfilling months of history.

The problem with polishing a data model alone

A transformation model is made of choices that look small on the page. Which timestamp counts as the event time? Is a cancelled order a row, a flag or a deletion? Does one row represent a customer, an account or a customer-account pair? Each choice seems obvious to the person who made it, because they have the source system’s quirks in their head. The reader of the finished table has only the column names.

If you refine the model privately, you tend to spend your effort on things you can measure: runtime, test coverage, naming conventions. Those are worthwhile, but none of them tells you whether the table answers the question somebody has. A flaw in the grain of the table, for instance, will survive every unit test you write and still wreck a monthly report. Evidence from many teams points the same way: the costly data errors are mostly mismatches in meaning, not bugs in code.

What an early draft looks like in practice

A rough draft of a data model does not need to run on full data. Three artefacts are usually enough:

  • A column list with one plain sentence per column describing what it holds and where it comes from.
  • Ten to twenty sample rows, hand-picked to include an odd case or two, such as a refund or a duplicated event.
  • A single stated grain: “one row per order line” or whichever applies.

That is a small package, and it can be written in under an hour. It is deliberately unfinished: no tuning, no documentation site, no scheduled run. The aim is for a reader to be able to say, with the sample in front of them, “that is not what I meant by active user.”

Be clear with yourself, too, about what “rough” permits. You are allowed to show a column you are unsure about, a join you have not tested and a sample that was assembled by hand. You are not allowed to hide the uncertainty. A draft that looks finished but is not will be treated as finished, and the reader will assume that anything odd is intentional. Label the shaky parts plainly, using phrases such as “not yet checked against the source” so that nobody builds on them by mistake.

Choosing who sees it

Pick the person who will query the table, not the person who would review the code. A fellow engineer can check join logic later. The earliest and most valuable reader is the analyst, product owner or finance colleague whose question the table exists to answer. If you can manage two readers, add one engineer who works on a neighbouring model, because that person notices naming and grain conflicts with tables that already exist.

Be careful to keep the group small. Posting a draft in a busy channel produces a flurry of reactions and no answers. One or two named readers, each told what you want, will give you more than twenty emoji.

Saying what kind of feedback you want

An open invitation to comment draws the easy remarks first. If you want help on substance, ask a pointed question and state what is out of scope. For a data model draft, three questions cover most of what matters early on:

  1. Does the grain match your question? Ask the reader to describe, in their own words, what one row stands for.
  2. Which column would you reach for first, and is it there? This reveals missing fields and misleading names.
  3. Which of these sample rows surprises you? Surprises point at hidden rules.

Then say which comments to hold: formatting, performance and documentation can wait. This one sentence of scope saves everybody time and makes candid answers easier to give.

Reading the response analytically

Treat reactions as data. When a reader hesitates on a column, record which column and what they thought it held. If two readers interpret the same field in two different ways, you have found a naming problem that would have caused argument for years. If a reader asks for something the sources cannot provide, you have found a gap in the project early enough to renegotiate scope.

It helps to sort observations into categories as you collect them:

  • Meaning: the reader and the author disagree on what a field represents.
  • Coverage: something needed is absent.
  • Surprise: a sample row broke the reader’s expectations.
  • Taste: a preference with no effect on correctness.

Act on the first three. Note the fourth and move on. The meaning category usually leads to the biggest changes and the biggest savings, because it is the one that otherwise remains invisible until a number is challenged in a meeting.

Another useful habit is to keep the feedback attached to the draft. Paste the reader’s answers beneath the column notes, with the date, and leave them there after the model ships. When a new colleague later asks why the table has two flags rather than one, the reasoning is sitting next to the code. That small record turns a private conversation into shared knowledge, and it saves the next person from re-asking questions that were settled at draft stage.

Why early beats late: the cost curve

Changing a model on a Tuesday afternoon, before any consumer depends on it, takes minutes. Changing it after dashboards, exports and downstream tables have been built on its shape means coordinating several owners, rewriting dependants and often repairing history. The same edit that was trivial at draft stage has a long tail later. This is the general reason that early feedback pays: the cost of change climbs with every dependency added.

For a concrete reference point, the site’s own write-ups on building transformations with dbt describe the sort of layered models where a small early decision about grain gets inherited by everything above it. And the article on validating data with Great Expectations in practice is a good companion, since tests are far easier to write once a reader has confirmed what the columns should contain.

A quick look beyond data teams

People who plan things in public have been doing a version of this for a long time. As a small illustration, KeralaOrbit is a Kerala events site with a discussion forum sitting next to its event listings, its venues and its blog, a layout that gives visitors room to raise questions before they commit to plans. The comparison is loose, but it points at the same behaviour: ask before the details are fixed.

A worked example, kept small

Suppose a data engineer is building a table of weekly active accounts. The draft sketch says one row per account per week, with a flag for whether the account performed any action. An analyst reads the column notes and asks whether “action” includes logging in or only creating content. The engineer had not thought to separate them. A short conversation produces two flags instead of one. Total cost: ten minutes, before any code was optimised. Had the table shipped with one flag, the discovery would likely have come when a leadership report showed an activity figure that nobody could reconcile with product usage.

Making it a routine

The habit sticks when it has a fixed place in the workflow. Many teams add a step to their model template: before writing the transformation, fill in the column notes and sample rows and send them to the named consumer. Others add a checklist item to the pull request template asking whether a downstream reader has seen the draft. Neither takes long, and both turn a good intention into a default.

  • Write the grain and the column notes first.
  • Pick a reader who will query the table.
  • Ask three pointed questions and name what to ignore.
  • Sort the answers into meaning, coverage, surprise and taste.
  • Edit the design before building on it.

The principle behind all of it is simple enough to say in a sentence: work that nobody else has seen is a set of guesses, and the cheapest time to test guesses is before you stack anything on top of them.

Related Posts

Five Myths About Leaving Data Pipeline Clean-Up for Later

Five common beliefs that keep data teams postponing pipeline housekeeping, and the plain-spoken reasons why small, immediate clean-up wins over the big sweep.

Read More

A DataOps Pipeline Teardown Checklist for a Finished Project

A fifteen-point checklist for reading a finished data transformation project room by room: layout, one traced column, tests, schedule and a written summary.

Read More

Seven Plain Ways to Rewrite Your Data Team’s Docs and Alerts

Cryptic pipeline errors and READMEs slow everyone down. Here are seven friendly rewrites that keep the detail and lose the fog.

Read More

Three Self-Imposed Limits for a Data Pipeline, Compared

A side-by-side look at three deliberate limits for a DataOps pipeline: a column budget, a SQL-only rule and a fixed sample size, and what each one reveals.

Read More

Pipeline Fallbacks in DataOps: Questions Teams Actually Ask

Answers to common questions about giving a data pipeline a fallback: what it is, how validation sets the trigger, and what a one-page plan should contain.

Read More

How a Data Engineer’s Near Misses Become Career Skills

Follow one junior data engineer through four close calls and see which career skills each one builds, plus a simple notebook habit anyone can copy.

Read More