Data dictionaries: agreeing on what a number means

Two analysts walk into a Monday meeting with two different numbers for last month's unit sales. Both are right. One counted multipacks as one unit and the other counted each can. A data dictionary prevents this. It's a document that defines every field and every metric in a dataset: what it's called, what it means, how it's calculated and where it comes from.

The myth is that everyone already knows what "units" means. They don't, and the disagreements cost more time than writing the definitions would have.

What goes into a data dictionary?

For each field, a few plain entries. The name as it appears in the data. A one-sentence definition. The type of value, such as a number, a date or a code. Where it comes from. And any rules or exceptions that affect it.

For each metric built from those fields, more detail. How it's calculated, step by step. Which records are included and excluded. What period it covers. And an example, ideally a small worked one, so a new reader can check their understanding.

A hypothetical entry: "Units: the number of individual sellable items scanned, as recorded by the register. A 12-pack scanned once counts as one unit. To convert to individual cans, multiply by the pack count field." One paragraph like that ends a whole category of arguments. The general practice is described well in the data dictionary entry.

Which definitions cause the most arguments?

Units, as above. Whether a multipack counts as one or many is the most common source of mismatched numbers.

Dollars, next. Do they include sales tax? Are discounts subtracted? Are returns netted out? Each choice produces a different total, and each is defensible. The dictionary should state which one applies.

Periods. Is a "month" a calendar month or a retail period of four or five weeks? Does a week start on Sunday or Monday? A figure for "July" can differ by several days depending on the answer.

Stores. Which stores are included in a total? All reporting stores, or only those open in both periods for a same-store comparison? The difference can be large.

Categories. Which items belong to which category? If the hierarchy changed, when did it change, and were past periods restated?

Who should maintain it?

One named owner, with input from everyone who uses the data. Without an owner, the dictionary goes stale within months. Definitions change, new fields appear, and nobody updates the document.

The owner doesn't need to write every entry. They need to make sure each entry is accurate, approve changes and communicate them. When a definition changes, everyone who uses the metric should hear about it before the next report goes out.

It helps to version the dictionary. Record what changed, when and why. Six months later, when someone asks why a trend line has a break in it, the change log answers the question.

How do you keep it current without a big effort?

Tie it to the work. Every time a new metric is created for a report, its definition goes into the dictionary before the report ships. Every time a question comes up about what a number means, the answer goes in too.

Keep it short and searchable. A dictionary that runs to fifty pages won't get read. One that fits on a few pages, organized by field and metric name, will.

And make it easy to find. Link it from every dashboard and report. The NRS Insights monthly reports explain the periods and comparisons they use, and each release is on the news page.