Building a CS Data Dictionary: The Unglamorous System That Saves Renewals

Nobody gets promoted for building a data dictionary.

There's no conference talk about it. It doesn't show up in your board deck. Your CSMs aren't going to thank you for it. And yet, in almost every CS org we've worked with that has a churn problem, a real, systemic churn problem, not just a bad-luck quarter the root cause traces back to the same place: nobody agreed on what the data actually means.

"Healthy" means something different to every CSM on your team. One looks at login frequency. Another weights support tickets. A third goes on gut feel from the last call. Your health scores are an average of those interpretations, which means they're measuring something, just not the same thing for every account.

That's a data integrity problem. And the fix isn't a better scoring algorithm or a new CSP feature. 

It's a data dictionary.

What a CS Data Dictionary Actually Is

A data dictionary is a shared reference document that defines every signal, metric, and field your CS team uses to evaluate account health and make decisions.

It's not a reporting dashboard. It's not your CRM field list. It's the document that answers: what does this number mean, where does it come from, and how should a CSM act on it?

A complete entry for a single signal looks something like this:

That's it. One signal, fully defined. The goal is to build that entry for every signal in your health score model, typically 8 to 12 for a mature CS org.

Why This Actually Saves Renewals

The connection between data definitions and renewal outcomes isn't obvious until you've seen what breaks without them.

Here's what breaks:

CSM coverage gaps. When "at-risk" isn't defined consistently, CSMs make coverage decisions based on their own threshold. One CSM flags an account at 55% engagement. Another doesn't flag until 30%. The second account churns before anyone acts. Not because the signal wasn't there, it was, but because nobody agreed on what it meant.

QBR and EBR theater. Without a shared definition of health, business reviews become narrative exercises. CSMs present the numbers that make the account look good. Without a standard, there's no way for a CS leader to push back or to compare accounts across the portfolio.

Forecasting that doesn't forecast. Renewal forecasts built on inconsistently defined health scores produce inconsistently accurate predictions. If you've ever had a "green" account churn, you know exactly what this feels like. The data wasn't lying, it was just measuring something different than what you thought.

Onboarding and handoff failures. When a new CSM inherits a book of business, they need to read account health fast. If there's no standard definition for what the numbers mean, every inherited account is a black box. That's not a CSM problem. That's a documentation problem.

A data dictionary solves all of these by establishing the one thing every high-performing ops system requires: a shared language.

How to Build One: The Four-Step Process

Step 1: Audit what signals you're actually using

Before you define anything, inventory it. Pull up your CSP and list every data point that feeds into your health score or that CSMs reference in account reviews. Include:

Don't include signals you wish you had. Inventory what's actually in the system and influencing decisions right now even informally.

Step 2: Identify the signals that actually matter

Most CS orgs are tracking more signals than they need and underweighting the ones that predict churn. Before you define everything, pressure-test your list.

For each signal, ask: has this ever actually predicted a churn or expansion outcome we could verify? If the answer is consistently "we're not sure," the signal may be noise. A health score with 15 inputs where 4 of them genuinely correlate with churn outcomes is better than one with 15 equally-weighted inputs built on intuition.

This step usually requires a conversation with whoever manages your data, CS Ops, RevOps, or a data analyst if you have one. Pull 12 months of churned accounts and map their signal history.

The patterns will be clearer than you expect.

Step 3: Write the definitions in plain language

This is the actual dictionary work. For each signal that makes the final cut, document:

Plain language matters here. If a new CSM can't read a definition and immediately understand what to do with the signal, rewrite it. The audience for this document is not the person who built it.

Step 4: Publish, train, and enforce

A data dictionary that lives in a Google Doc nobody opens is not a data dictionary it's a graveyard of good intentions.

To make it operational:

Publish it where CSMs already work. If your team lives in Notion, put it in Notion. If you're a Confluence shop, it goes in Confluence. Don't create a new system to house the document that helps people use the existing systems.

Build it into onboarding. New CSMs should review the data dictionary in their first week. It should be as standard as the product overview and the customer segmentation guide.

Reference it in QBR prep. Make the data dictionary the baseline for how accounts are assessed before every business review cycle. If a CSM is calling an account "healthy," they should be able to point to specific signals and thresholds, not just a feeling.

Review it on a cadence. Your signals will change as your product evolves, your customer base matures, and your health score model improves. Build a quarterly review into your CS Ops calendar. The owner for each signal is responsible for flagging when the definition or threshold needs to change.

Common Objections (and How to Handle Them)

"We don't have the data infrastructure for this." You don't need a data warehouse to build a data dictionary. Start with what's already in your CSP and CRM. Define the signals you have. That alone will surface alignment gaps you didn't know existed. The infrastructure conversation comes after you've agreed on what you're trying to measure.

"This will take too long to build." A first version of a CS data dictionary covering the 8–12 signals that actually drive your health score takes one working session plus a documentation sprint. That's a half-day of CS Ops time and two or three async reviews from CSM leads. You're not writing a textbook. You're creating alignment on a defined list of signals.

"Our CSMs won't use it." They will if it's built into the workflows they already use. The failure mode for internal documentation is always the same: it gets built and then never connected to the systems where work actually happens. Embed the dictionary in your QBR prep process, your CSM onboarding, and your health review cadence and it becomes the baseline, not a reference document people have to remember to check.

What Good Looks Like

A CS data dictionary is working when three things are true:

1. Two CSMs looking at the same account reach the same health assessment. Not the same recommendation the same read of the data. Judgment calls on next steps can vary. The interpretation of a 42% engagement score should not.

2. A CSM who inherited a book three months ago can explain why any account is in their current health tier. If the answer is "I think they're probably okay," the dictionary isn't being used. If the answer is "their engagement score dropped below threshold in February and I've had two check-in calls since," it is.

3. Your renewal forecast has gotten more accurate quarter over quarter. This is the lagging indicator that tells you whether your shared definitions are actually predicting outcomes. It won't happen immediately, but after two to three quarters of consistent data dictionary use, the signal-to-churn correlation should sharpen.

Start Smaller Than You Think You Need To

The most common mistake teams make when building a data dictionary is trying to define everything at once. They map 20 signals, get halfway through the documentation sprint, hit organizational friction on a few contested definitions, and abandon the project.

Start with the three to five signals that feed your churn risk flag. Get those fully defined, adopted, and reviewed through one QBR cycle. Then expand.

A partial data dictionary that's actively used beats a complete one that isn't. Build the habit of shared definition first. The coverage follows.

The CS leaders who build this infrastructure aren't the ones doing the glamorous work, the keynote speeches, the AI pilots, the big expansion plays. They're the ones whose teams don't have surprise churns in Q4. They're the ones whose forecasts are accurate. They're the ones whose new CSMs ramp in weeks instead of quarters.

The unglamorous work is often the most load-bearing. A data dictionary is one of the best examples of that in CS ops.

Build it once. Maintain it quarterly. Let it do the quiet work of keeping your renewals where they belong.

ScaleUp CS builds the operational infrastructure that makes CS teams scalable and defensible. If you want help auditing your health score model or building your first CS data dictionary, let's talk.