A useful metric dictionary explains the decision, unit, formula, population, time basis, source and owner for each measure. Include exclusions, limitations and worked boundary cases. Link definitions from reports and version changes so another person can reconstruct the result without relying on the original analyst.
Write for a reader making a decision
Start with a plain statement of what the measure means and why it is used. A formula alone cannot explain whether a metric is suitable for a staffing decision or a customer comparison. Name the observation unit, such as order, organisation or hour. Provide a short interpretation and the important uses the metric cannot support, avoiding an encyclopaedic page that hides the actual definition.
Give the metric a stable identifier separate from its display label. Labels may be shortened on a chart, while the identifier links reports, queries and change records to the same concept. Identify the accountable business owner and the technical source maintainer. Those roles can overlap, but the entry should make clear who can clarify meaning and who can repair a broken data feed.
Include enough detail to reproduce the calculation
Specify numerator, denominator, eligibility and exclusions. Record the event clock, time zone, observation window and treatment of late arrivals. Name sources at a level that identifies the actual dataset or interface, while keeping credentials and private connection details out of the dictionary. Explain missing values and zero denominators explicitly. A phrase such as active customers divided by customers merely moves the ambiguity into two undefined words.
Include a worked example and boundary cases: cancellation before completion, event exactly at midnight, unknown status or customer with several accounts. State rounding and currency conventions where relevant. Link to the controlled implementation without making code the only accessible definition. The business meaning should survive a tool migration, while the implementation reference helps establish how the current report applies that meaning.
Keep the dictionary connected to real reports
Link the entry beside the metric in the dashboard or exported report. Record definition version and effective date, with a short change note explaining whether historical values were recalculated. A dictionary that updates independently of the report can create false confidence, so include a review step when source semantics or eligibility logic changes. Preserve retired versions for interpreting old publications.
The government framework is further reading on documented data fitness and quality. The example below is fictional and illustrates a metric entry rather than a mandatory standard. Review the dictionary with someone who did not create the measure: ask them to calculate the worked case and explain an exception. Difficulty doing so is evidence that the entry needs clearer rules.
Avoid filling every field with reassuring boilerplate. If source coverage or a denominator is unknown, state the gap and its owner. An incomplete but candid definition is more useful than a complete-looking form that conceals unverified assumptions behind polished language.
Fictional dictionary entry: fulfilled-order conversion
A fictional scenario to explain the method, not a customer result or a market benchmark.
A fictional company creates metric CONV-30, labelled thirty-day fulfilled-order conversion. Its unit is eligible enquiry opportunity. The denominator is distinct non-test opportunities entering in a calendar week; the numerator is those opportunities linked to at least one fulfilled order within thirty elapsed days, using the agreed reporting time zone. Cancelled unfulfilled orders do not qualify.
For 80 eligible opportunities, 24 qualify after all members mature. The rate is 24 divided by 80, or 30%, displayed to one decimal place as 30.0%. Five additional orders belong to older cohorts and are excluded from this numerator. The entry identifies the source opportunity and fulfilment feeds, the commercial owner and the late-arrival revision rule.
Version two later changes the window to forty-five days and receives a new comparison note. These invented records demonstrate a reproducible entry; they do not establish that thirty days is appropriate or that the metric measures the causal effect of a sales intervention.
TAKE THIS INTO YOUR NEXT CONVERSATION
A practical next-step checklist.
- State meaning, decision and observation unit.
- Specify formula, population, clock and exceptions.
- Include a worked case and named owners.
- Link reports to versioned definitions.
Common questions.
Must every dictionary entry include code?
A controlled implementation link helps, but the plain-language definition must remain understandable without reading code.
Can the display label change without changing the metric?
Yes if meaning stays fixed and the stable identifier remains linked. A changed eligibility rule needs a definition version.
Further reading & source context.
These primary references provide background. They are not evidence for the fictional example above and do not endorse Accuralytix.
Found an error or a missing qualification? Send an editorial correction.
Check my data readiness.
Use a practical tool to turn this idea into a clearer starting point.
Check my data readiness