A platform team published a migration guide six weeks ago and 40 of 60 service teams have migrated. The page has 2100 views and the code-sample section 1950 while the rolling-back section anchor has 31. The 20 teams that have not moved all run the same older runtime version. Which diagnosis fits the signals?

Reading the three numbers

2,100 page views and 1,950 at the code sample means 93% of readers got most of the way down the page. Whatever is wrong, it is not that the document is too long or that people are not reading it. That single ratio eliminates the two most popular explanations before you look at anything else.

The signal that matters is not in the page analytics at all. It is that the 20 non-migrators share a technical attribute. Twenty teams independently choosing not to migrate would not correlate with a runtime version; twenty teams hitting the same wall would.

The diagnosis

A guide written from one worked example works for every team whose shape matches the example and stops dead for the rest. The older runtime almost certainly needs a different dependency version, a different configuration key, or a shim the guide never mentions. Those teams read the guide, reached the sample, found it did not apply, and had nowhere to go - which is also why they did not file 20 tickets: there is nothing to report except "this does not cover us", which feels like their problem.

The misleading signal

The 31 views on the rolling-back section. It looks alarming - 40 teams migrated and almost none read the rollback instructions - and it is normal. People read rollback instructions when they need to roll back, which is after. Chasing it costs a day of rewriting and changes nothing. A genuinely worrying rollback signal would be high views combined with a low completion rate, which is the opposite shape.

Why the other options fail

• "Too long, they stopped reading." Contradicted by 1,950 of 2,100 reaching the sample. This is the reflex explanation for any documentation problem and the analytics rule it out in one line.
• "Wrong channel, they need a deadline." A deadline applied to a team that has no working path produces an escalation, not a migration. Deadlines fix priority problems and this is not one.
• "They are under-resourced." Under-resourcing is uncorrelated with runtime version. If the 20 split across runtimes and clustered under two engineering managers, this would be the right answer.

The fix and the alert that would have caught it earlier

Instrument by consumer, not by page. Join the guide's analytics to the migration ledger - team, runtime version, migrated yes or no - so the unit of analysis is the consumer rather than the pageview. Then add the second worked example, which is a day of work.

The decision rule generalises: when adoption splits cleanly by a technical attribute of the consumer, it is a coverage gap; when it splits by team or by reporting line, it is a priority problem. Only the second one is fixed by a deadline, and applying the wrong remedy to the other burns the platform team's credibility with the teams least able to comply.

The alert worth having: flag any migration programme where the migrated fraction is flat for two consecutive weeks and the remaining population shares a single attribute. That combination is a content gap, and it is detectable in week three rather than week six.

When this is the wrong diagnosis

If the 20 stalled teams split evenly across runtimes but cluster under two engineering managers, the coverage explanation collapses and the priority one is correct. The same applies when the guide is new and the window is young: at week two a 40-of-60 split is just the adoption curve, and reading a content gap into it produces a second worked example nobody needed. Wait for the attribute to correlate before writing anything.