Why do we need written definitions for our metrics?
Because most reporting arguments are definition arguments in disguise. "Lead," "job," "close rate" and "revenue" each have several defensible meanings, and two people using different ones will never reconcile. A written definition — source system, date field, inclusion filter, exclusions, refresh, owner — turns a recurring argument into a lookup, and lets you change a definition on purpose with a date attached.
What an entry has to contain
- Name and plain-language meaning. One sentence a non-technical manager would agree with.
- Source system. Which system is authoritative for this fact.
- Date field. Which timestamp places a record into a period. The most-skipped field and the most-common cause of disputes.
- Inclusion filter and exclusions. Statuses, business units, job types in and out.
- Refresh and owner. How current it is, and who to ask when it looks wrong.
The three most contested terms
Lead is the worst. An ad platform conversion, a tracked call over a duration threshold, a CRM record, and a booked customer are four different things and all four get called a lead. Sum reports built on different ones and a single customer counts several times.
Close rate is second: closed against what denominator — opportunities, estimates issued, dispatched jobs, or calls? Each produces a wildly different number. Revenue is third, because booked, invoiced and collected are three different moments. These are the same fault lines that make revenue reporting hard to reconcile across systems.
Definitions need version dates
If you tighten the definition of a lead in March and do not record it, every trend line crossing March shows a change that never happened in the business. Six months later somebody will build a theory on it.
Stamp each definition with an effective date, keep the old one readable, and note on affected charts where the change falls. This costs almost nothing at the time and saves an entire investigation later.
Who maintains it
One person, not a committee, with the authority to settle disputes. The dictionary is a governance artifact, not a documentation exercise — its value is that it ends arguments, and that only works if someone has the final word.
In practice the definitions live alongside the integration itself, so the query and the documentation cannot drift apart. That coupling is a good thing to insist on when you evaluate any reporting build.
Keep it next to the number
A dictionary in a shared document is a dictionary nobody opens. The version that gets used lives inside the reporting: every metric label links or hovers to its definition, and the definition shown is the one the query actually used.
That coupling has a second benefit — it makes definition drift visible. If the documentation and the query are stored together, changing one without the other becomes obvious rather than something discovered a year later during a reconciliation.
Topics: metric definitions · data dictionary · governance · reconciliation
Have a version of this question about your own business?
The useful answer usually depends on which systems you run and how they're connected. That's a conversation, not a blog post.