How Do You Document a Dashboard Metric?
From the earlier reference collection. Read the current software blog.
A metric definition should expose the records and calculation behind the number, the time window and units used, and the limits on what it represents.
Define inputs and calculation
Name the source fields and records included. If a metric excludes incomplete readings, canceled trips, or duplicate events, state the rule. Describe the calculation in enough detail for an independent reader to reproduce it: count, sum, mean, ratio, percentile, or another operation. A label such as “average delay” is incomplete until it defines which trips and which delay values enter the calculation.
Explain the aggregation order when it matters. Averaging daily averages can produce a different result from averaging every underlying observation, especially when days contain different numbers of records. A metric note should say which method is used and what happens when a denominator is zero or inputs are absent. If the metric is derived from a source rather than directly measured, make that distinction clear.
Specify window, units, and display
Define the time window with boundaries and time zone. “Today” could mean a calendar day in the viewer’s zone, a provider’s service day, or a rolling 24-hour period. Give an example, such as “the interval from midnight through the current time in the station’s local zone,” if that is the actual rule. State whether the current partial interval is included and when the value refreshes.
List the unit and how the displayed number is rounded. If a value is converted from one unit to another, document the conversion and whether calculation happens before or after rounding. For example, a rate computed from unrounded counts may differ slightly from a rate computed from displayed rounded counts. Keep precision consistent between charts, exports, and tooltips, or disclose where it differs.
Set interpretation limits
Explain what the metric can and cannot support. A rate from reporting stations does not necessarily represent all stations; a daily count may omit late-arriving records; a median can conceal extreme values. Note coverage thresholds or suppression rules that change whether a metric is shown. If the underlying data are revised, say whether historical values are recalculated or remain as originally published.
A reader comparing two dashboard cards should be able to tell whether they share the same population, time zone, window, and unit. If not, make the difference visible in the labels and notes. A practical definition might say that “daily total” sums completed hourly records from local midnight to midnight, excludes incomplete hours, and rounds only for display. That description makes the number interpretable and gives maintainers a basis for checking that code and documentation still agree.