Goals and funnels

Pageviews cannot tell you whether the documentation worked. A goal is you stating what "worked" means for your project; a funnel is you stating the route to it. Everything below is then measured against those statements rather than against a default somebody else chose.

What you get#

Name an outcome — reached_pricing, copied_the_install_snippet, left_for_signup — and Docsbook reports how many visits completed it over the window, with the daily series behind it, and (if you declared what one is worth) what they were worth. String several into a route and you get a step-by-step funnel that names the worst transition, not just the smallest step.

New goals are matched retroactively against the history already recorded, so a goal you declare today reports last week's numbers immediately instead of starting from zero.

The four kinds of goal#

An event goal can be narrowed to one page with an optional scope, which is what lets a single event be two different goals — "copied the quickstart snippet" and "copied the auth snippet" are the same event on different pages.

How it is built#

Counted per visit, never per event. A section goal fires every time a reader scrolls past that heading; counting events would report one person as five conversions. Funnel potential value goes further and counts per person, so a reader who walked the route twice contributes one reader's worth rather than two.

Order is enforced by comparing hit times, not by membership. For each step, Docsbook looks for the first hit at or after the previous step's hit. A reader who landed on step 3 first and only later saw step 1 is correctly not counted as having reached step 3.

The conversion window bounds how long a later step still counts. Leave it empty and the visit itself is the window, which is the honest default for a docs site. Set it, and it is clamped to the history that actually exists — a window longer than retention describes conversions that can never be observed.

Rates are suppressed on thin data. A funnel's overall conversion rate is withheld below 30 visits, and each step is flagged lowSample when the step before it had fewer than 30 — so a solid step 2 still quotes a rate while a thin step 5 does not. Median and p90 time-to-convert are withheld below 5 conversions, where the list of converters is the answer and a percentile is not.

leak_index names the worst transition, not the smallest step. The smallest step is almost always the last one; the biggest proportional drop between two adjacent steps is where the route actually breaks.

Money stays off unless you switch it on. A goal value of 0 is refused outright — null and 0 are different claims, and only one of them belongs in a revenue figure. Where no value is declared, money columns are blank rather than $0.

What the validator refuses, and what it only warns about#

These are enforced identically whether you create a goal in the panel, over MCP, or through the assistant — one rule, so no surface accepts what another rejects.

Deleting a goal archives it rather than destroying it, because a funnel step pointing at a vanished goal would otherwise take the step with it.

The reports built on top#

Time-to-convert is reported as median and p90, never a mean. Time to convert on a docs site is bimodal — readers who arrive ready, and readers who evaluate for weeks — and the mean lands in the empty valley between the two modes, describing a visitor who does not exist.

The reverse funnel needs no hypothesis. A declared funnel can only measure the route you thought of; working backwards from successful visits reports the route readers actually found, which is often one nobody designed. When that route is real, the action is to promote its entry point in the navigation.

Potential value is a readiness share, not a forecast. Where a reader has not converted, Docsbook can still rank them: it builds a profile of what converters looked like before they converted — reading time, pages, and crucially the pages converters open more than everyone else — and scores each reader against it. A page opened by 80% of converters and 8% of everyone else carries the finding; a page opened by 92% and 90% carries nothing. The profile is only built at 5 or more converters and carries at most 12 discriminating paths.

Why this is the right way#

Limits and open questions#

• A visitor is a hashed IP. Every count here inherits that: corporate NAT merges readers, mobile networks split them. Read five rows of goal visitors to learn who is evaluating you; do not read the total as a headcount. See How measurement works.
• The source shown on a journey is last touch and over-credits Direct. Treat it as a hint, never as attribution.
• Retention cohorts are capped by 30-day history. W4 needs a 30-day window to exist at all; on a 24-hour or 7-day period it is structurally zero and means nothing. There is no year-over-year view and there cannot be one.
• Retention has no universally good direction. High return is healthy for reference documentation and a failure for onboarding — the number cannot know which section it is describing.
• Potential value is reasoned, not fitted. Its weights are not calibrated against an observed base rate, so it ranks readers against each other honestly and must never be summed into a pipeline figure.
• A funnel measures the route you declared. If readers succeed by a path you did not describe, the funnel will report failure while the reverse funnel reports the truth. Read both.

Related#

• How measurement works — the visit definition, the bot filters and the sample floors every number here inherits
• Analytics overview — conversion rate and revenue in the headline strip
• Tracked events reference — the event names an event goal can match
• MCP tools reference — create_goal, create_funnel, get_funnel, get_retention and the rest