Before building a dashboard, agree what its numbers mean. A business metric dictionary records the question each measure answers, how it is calculated, which records qualify and who approves changes. It gives the reporting team a definition to implement and users a definition they can challenge.
A chart can be technically correct and still mislead a meeting if two teams interpret its label differently. Resolve the disagreement at the definition level before choosing a visualisation or connecting another data source.
Start with one number people interpret differently
Choose a contested measure such as “conversion”, “active customer” or “completed order”. Ask each stakeholder to describe what they would count from a small, shared set of fictional records. Differences become easier to discuss when they concern particular events rather than abstract terminology.
If stakeholders need the broader context, start with the business intelligence fundamentals before agreeing individual measures.
Write the business question beside the proposed name. “How many checkout sessions resulted in an order?” differs from “How many authorised payment attempts resulted in an order?” Both can be useful, but a single label should not hide their different populations.
A business metric dictionary also differs from a technical data dictionary. A schema description can explain a column's type and location without deciding whether that column represents the event the business intends to measure. Connect the two documents rather than expecting either to replace the other.
Microsoft Purview's glossary guidance illustrates the role of shared terms and ownership in data governance. A metric definition adds calculation and interpretation rules to that broader concern; it does not require every organisation to adopt the same cataloguing tool.
Write the counting unit, population and formula
Start with the unit: a person, account, order, session or event. Then define the eligible population. A customer with several accounts and an order with several payment attempts make these distinctions consequential. State when duplicates are combined and when separate records represent real separate activity.
For a ratio, describe the numerator and denominator independently before writing the division. Record whether they refer to the same cohort and window. Decide how missing identifiers, cancelled records, test accounts and incomplete events are treated. Exclusions should be visible decisions, not undocumented filters in a report.
Use a definition card that someone outside the reporting team can read:
- Name and question: the specific decision the measure supports.
- Counting unit and eligibility: what enters the calculation and why.
- Formula: numerator, denominator, grouping and treatment of an empty population.
- Time rule: the event date, reporting window and time zone.
- Lineage: source fields and transformations used to calculate it.
- Owner and version: who approved the meaning and when it applies.
Coalesce's metric documentation examples provide context for documenting purpose and calculation. The card above is an illustrative working aid, not a copied vendor template or a promise that a particular dashboard tool stores these fields.
Define time rules and data lineage
“This month's orders” needs more than a date picker. Decide whether an order belongs to the date it was placed, paid, fulfilled or entered into the reporting system. Choose the reporting time zone and explain how events near a boundary are handled.
Event time versus reporting time
A late-arriving record may describe yesterday's activity while becoming available today. Specify whether past totals are restated and how users recognise a provisional period. Otherwise two downloads taken on different days can appear contradictory even when the calculation follows its intended rule.
Trace the measure back to its sources. Record where identity matching, status mapping and exclusion rules occur. A dashboard displaying a pre-calculated value needs to identify the upstream definition rather than merely pointing to the final table.
Document transformations and exclusions before data analytics work turns raw records into a reported number.
Also record refresh expectations separately from event time. An hourly import does not make a measure a live operational count. Where two systems disagree, identify which source owns the relevant fact and who investigates discrepancies. The dictionary should make that uncertainty discoverable rather than concealing it behind a precise-looking number.
Work through two competing definitions
Consider a deliberately simplified fictional sample with 100 checkout starts, 50 authorised payment attempts and 40 completed orders. Assume the sample has already been linked and reviewed for the purposes of this illustration. These invented counts are not a customer result or an ecommerce benchmark.
| Definition | Calculation | Question answered |
|---|---|---|
| Completed orders per checkout start | 40 ÷ 100 = 40% | What share of the defined checkout-start population completed an order? |
| Completed orders per authorised attempt | 40 ÷ 50 = 80% | How does completion compare with the defined authorised-attempt population? |
The difference does not show that one team calculated badly. The denominators answer different questions. Neither percentage explains why a checkout was abandoned or an authorised attempt did not become an order.
In real data, challenge the simplified assumptions. One checkout might involve several attempts, an order might complete after the reporting window and a missing identifier might prevent reliable linking. Decide whether the desired measure needs a cohort calculation rather than dividing two independent period totals.
Add a handful of boundary records to the acceptance example: a cancellation, a repeated attempt and a completion after midnight. For each, the owner should be able to explain inclusion or exclusion. These small examples often expose a hidden disagreement more clearly than comparing two large totals.
Assign ownership and a change process
Name a business owner for meaning and a technical owner for implementation. They may work together, but the responsibilities differ. A developer should not have to decide whether a cancelled order counts towards a commercial measure because nobody else owns the question.
When a definition changes, record the reason, new version, effective date and affected reports. Decide whether historical periods are recalculated or remain under the old definition. A sudden movement caused by a rule change should be distinguishable from a change in business activity.
Keep acceptance examples with the definition. They provide a shared reference when a source system changes or a report is rebuilt. They do not prove every production record is correct, but they make important assumptions reviewable.
Provide a route for disputes too. If sales and operations need different measures, use clear names and explanations rather than forcing both into one ambiguous “official” number. Ownership should resolve meaning, not suppress legitimate differences in questions.
Mark deprecated definitions clearly. If a report retains an older calculation for comparison, its label or supporting explanation should make that version discoverable. Reusing a familiar name for a changed denominator can otherwise make an apparent trend describe two different questions.
Use the dictionary to scope dashboard work
Bring a short approved set of definitions to dashboard planning. For each measure, identify whether the required data exists, whether access is available and which transformation or reconciliation work remains. This separates a missing chart from a missing business rule.
Prioritise the measures that support real decisions. A smaller dashboard with agreed definitions can be easier to use than a crowded report whose labels require an explanation in every meeting. Keep unresolved definitions visible as requirements rather than presenting them as completed reporting features.
Discuss business intelligence requirements with ZakCodeX once the definitions and their owners are visible.
