SPONSORED

Sponsored by Databricks. Databricks commissioned and funded this guide and reviewed it before publication for factual accuracy. They did not get to change the conclusions.
Full disclosure at the foot of this post.

A badly written data request rarely gets refused. It gets built.

That is the part people miss when they complain about the queue. You ask for lapsed customers, three weeks later you get lapsed customers, and the team who built it did exactly what the message said. Then the campaign underperforms and nobody can point at the mistake, because there was not one.

Lapsed meant a hundred and eighty days in the warehouse and ninety in your head. The message never said which, so somebody chose.

That is a different failure from the one in guide 1.

There, two people used one word for two things and found out weeks later. Here everybody understood the words perfectly well. The request simply did not say enough to be built from, and the person who picked it up filled the gaps so they could get on with their afternoon.

Guide 1 opened on this, which I have seen a version of in most Slack channels I have been let into:

Can you sync the lapsed-customer audience to Braze in real time? Just needs the churn model score on each profile.

Raise your hand if this all seems very familiar to you.

Guide 1 asked what its words mean. This one asks what is missing from it. Six things, as it turns out, and every one of them is a decision that gets made either by you now or by somebody else later.

One thing this is not about before we truly dive in.

It is not about writing more, or writing more politely. The rebuilt version at the bottom of this piece is five sentences long. The point is which five.

Who you mean

The message says "the lapsed-customer audience." That is a label, and labels do not survive the trip. Every system in the building has its own idea of lapsed, none of them is written down, and the one in your head is not any of them.

Write the condition instead of the label. Customers who have bought at least once and have no purchase in the last 90 days, from the orders table, where a later-refunded order does not count as a purchase.

That sentence is longer than it wants to be, and it took three attempts to get there, which is the part worth telling you about.

I wrote "lapsed customers" first.

Then "no purchase in 90 days, refunds excluded", which sounds specific and is not:

It can mean the refunded order does not count, or that anybody who has ever had a refund is out of the audience entirely, and those are different groups.

Then somebody read the fixed version and asked whether people who have never bought anything at all qualify. Which they do, under that wording.

They have no purchase in 90 days.

They have no purchase in any days.

An audience built to win back lapsed customers would have gone out to a pile of people who were never customers.

Three passes on one sentence, each one finding a label hiding inside the last fix. That is not me being careless. It is what the whole thing is like, and it is why the answer is to write the condition down where somebody can argue with it rather than to think harder in private.

The exclusions are where this goes wrong without anyone noticing. Test accounts, employees, people who bought through a channel you do not own. Somebody has to decide about each of those, and if you do not, they will, using whatever seems reasonable on the day.

The key that has to travel

"On each profile" tells them nothing about how the records get matched at the other end.

Write which identifier travels the whole way. Keyed on the hashed email, which is what our Braze setup matches on.

Note the "our". Most destinations can match on several things, so naming the one yours is configured for is a different claim from naming the one the product supports.

This is the one where the failure is quiet and expensive.

Records arrive, the job reports success, and the campaign reaches a third of the list because two thirds could not be matched on the key that was sent. The dashboard says it worked. Guide 1's entry on customer is the same problem one step earlier, and guide 4 goes into what happens when the key is right and the matching is not.

When, how often, and why then

"In real time" is the most expensive phrase in the message, and guide 1 already made the case for why. What it does here is worse than ambiguity: it gets priced.

Write the deadline, the cadence and the reason behind them. In place by 07:00 CET and refreshed daily, because the send goes at 09:00 CET.

Put the time zone in. It looks like pedantry right up until the team building it is in another one, and then it is the difference between a morning send and an afternoon one. If the job is new rather than recurring, say which morning it has to start, because otherwise "daily" begins whenever the work finishes.

A deadline with a reason attached can be negotiated. Somebody can come back and tell you that 07:00 costs four times what 23:00 costs, and ask whether the send could move. A speed with nothing behind it cannot be argued with, only quoted for. I wrote about where vendors draw that line in real-time from a warehouse, and guide 3 is entirely about the cost.

Where it lands, by what method, and in what shape

"Sync it to Braze" names a destination and stops. Arriving somewhere is not the same as arriving usable, and naming a destination is not the same as naming a route into it. Most tools of any size offer several, and they differ in cost, latency and who has to maintain them.

Write the route and the shape as well as the place. Into Braze via the existing scheduled sync, with the churn score as a number 0 to 100 and the other fields as in the attached list.

The churn score is worth its own sentence, because it was in the original message and it is the sort of thing that falls out of a request while the request is being tidied up. It is the only part of that first version that was specific, and specific things deserve to survive.

Export the destination's field list and attach it. It takes a minute, and it settles two days of exchange about names, types, and which fields are mandatory. Of everything in this piece, that is the cheapest minute available.

How much, and how far back

The message says nothing about size. Almost none of them do, and this is the omission that turns a small job into a stalled one.

Write the numbers. Roughly 40,000 records, current state only, no history.

Volume is the obvious half. History is the half that costs, and the half nobody writes down. Forty thousand current records is a small job. Forty thousand records with three years of behavior behind each one is a different job with a different bill, and the request that produced both of those reads identically. If you do need history, say how far back and why, because a backfill is usually a one-off piece of work that has to be planned around everything else rather than a setting somebody flips.

Left out, the job gets scheduled as though it were free, and the conversation about whether it is affordable happens after somebody has already built it. That conversation goes much better before.

What tells you it worked

Also missing, and also missing almost every time.

Write what you will judge it on. Judged on a purchase within thirty days of the send by somebody in the audience, which is already instrumented, and spot-check twenty records against the orders table before the first send.

I had written "30-day reactivation" there, which is a phrase I have said out loud in meetings for years and which means nothing reliable to anybody who has not been in those meetings. In the sentence about the measure. In a guide about not doing that.

Two things come of saying it. The people building it can tell you when your measure cannot be calculated from what you have asked for, which happens more often than you would like. And when it ships, there is a number rather than an argument. Without one, the work goes out, nobody can say whether it worked, and the next request starts from nothing. Guide 6 is about writing that measure so a system can act on it.

The spot-check is the cheap half of that sentence and it does something separate. A measure tells you whether the campaign worked. Twenty records read against the source tells you whether the thing you are measuring is the thing you asked for. Those fail independently, and the second one fails silently, which is why I would rather find out on twenty rows than on forty thousand.

Three of these are yours, and three are a conversation

Six questions handed to one person reads like homework, and that is a fair reason to put the sheet down. So it is worth saying which ones are actually yours.

Who you mean, when it has to be there, and what will tell you it worked are yours alone. Nobody else can answer them, and nobody else should try. The identifier, the destination and the route into it, and the volume and history are the other three, and those are questions about somebody else's system that you are not expected to answer on your own. On the sheet they are marked shared, for exactly this reason.

That leaves three sentences you have to be able to write, which is a much smaller ask than six, and it is the honest version. If your request names the audience as a condition, the deadline with a reason, and the measure, the other three become a short conversation rather than three weeks of silence.

Some of these you cannot answer, and that is fine. You may not know how many records there are, or which identifier the destination keys on, because those are questions about somebody else's system.

Say so explicitly, and on the shared three that is the whole job. "I do not know what the volume looks like, can you tell me before we size this" is a request. Silence in the same place is an assumption, and it will be resolved by whoever picks the ticket up without either of you noticing it happened.

Naming the gap is worth almost as much as filling it. It tells the person reading that you know the decision exists.

The same message, rebuilt

Can you send customers who have bought at least once and have no purchase in the last 90 days, from the orders table, where a later-refunded order does not count as a purchase, to Braze, keyed on the hashed email our Braze setup matches on. It needs to be in place by 07:00 CET and refreshed daily, because the send goes at 09:00 CET. Via the existing scheduled Braze sync, with the churn score as a number 0 to 100 and the other fields as in the attached list. Roughly 40,000 records, current state only, no history. We will judge it on a purchase within thirty days of the send, which is already instrumented, and spot-check twenty records against orders before the first send.

Five sentences, and nothing in it that somebody would otherwise have had to guess.

Before you send the next one

Take the request you were about to send and read it against the six. Mark the ones it does not answer, and fill those in, including the ones you think are obvious. Obvious is where this goes wrong, because obvious to you is a definition nobody else has seen.

It moves the argument from week six to this afternoon, which is the only place it is cheap.

And it works in the other direction too. If you are the one receiving a one-line request, the sheet is a reasonable thing to return with a note about which question it does not answer. That is a more useful reply than asking what they mean by lapsed, and it costs a good deal less than building it twice.

Next in this series: what real time actually costs. All six live on the Helping Marketing Talk to Data Engineering page as they publish, and every term across the series is collected in the glossary.

About the series