Four principles
Four rules we chose to follow
The gray line under each principle is what we could have done instead — easier, better-looking, and unable to survive a client's review.
Zero samples read "no data", never 0%
When an engine yielded no valid samples this period, the report says "no valid sampling this period" — not 0%. "Not measured" and "measured at zero" are opposite findings: one is missing data, the other is a real negative result.
The easier route: print 0% — tidy tables, pretty charts, and clients misreading "this engine never mentions us" when the truth is we never measured it.
Every metric carries its denominator and sample size
Every external number states its numerator and denominator (e.g. mention rate = mentioning samples / valid samples) plus the sample size. Insufficient samples are labeled as such, with no conclusion drawn.
The easier route: hand over a single percentage — unverifiable, incomparable, and impossible to explain when questioned.
Data from different capture methods never merges into one trend line
Official API, UI simulation, manual entry and third-party sources are recorded and presented separately. Averaging two methods produces a line that looks perfectly normal and does not exist in reality.
The easier route: draw one smooth line mixing everything — visually "complete", and describing a trend that never happened.
A "false improvement" self-check: every change must be explainable
Re-tests disclose a measurement-condition snapshot (question set, platform set, competitor set, sampling window). When a model or question-set change moves the numbers, the report marks the periods as not directly comparable — measurement changes are never repackaged as optimization wins.
The easier route: hide the change — up means "optimization worked", down means "model fluctuation".