Docs Intent Signals Playbook 2026
A team reading your API reference is telling you what it wants to build. This play turns docs reads from identified accounts into evidence the weekly check reads beside usage against your benchmark, and puts the move on the account in your CRM: an expansion note for the AE, a help offer for the job they're reading about – or no move, with the reason noted.
A team that spends a week in your API reference is telling you what it wants to build. Unless someone ties those reads to the account, they stay a page-view count in your docs analytics.
This play makes docs reads from identified accounts one more piece of evidence in the weekly check. Growth reads strengthen an expansion move; risk reads add context to a gap. Either way, the move lands on the account in your CRM with the pages read attached, and your team decides.
Measure it on docs reads that became a recorded move, expansion deals with a docs read as evidence, help offers accepted, and the revenue behind them.
How it works9 steps
01SignalPut docs reads beside usage against the benchmark
Build the benchmark once, refresh it quarterly:
- Comparison customers: same segment (plan tier, size band), 12+ months as customers, renewed at the same or higher revenue. Aim for 20; with fewer, label it low confidence.
- What they do and pay: median weekly active users as a share of seats, weekly use of your core features, and median ARR. Your CS lead approves it. The benchmark play has the full method.
Then group your docs pages once:
- Growth: API reference, integrations, advanced features, pricing and limits, anything that describes a higher plan.
- Risk: data export, cancel, migration, delete account.
- Routine: everything else – getting started, troubleshooting.
Each week, for each account: pages read by group, who read them and their role, plan and ARR against peers, and usage against the benchmark – the account's active share of seats as a percentage of the benchmark's (default). A read counts when one known reader views three or more pages in one group that week, or two known readers each view a page in the same group (defaults). Under about a hundred accounts, do it by hand.
02ScoreSort the read and check the records
- Growth, risk or routine: the group with the most pages wins. A week with both growth and risk reads is a risk read.
- On their plan already? If the feature they're reading about is on their plan, the job is help, not a sale.
- Deal, renewal or cuts: open deals, renewal stage and 90 days of CRM notes and tickets.
Say an account pays $12,000 a year on the Team plan and runs at 90% of the benchmark. An engineer and an admin spend the week in the webhooks and API-auth pages; the higher API limit is on the Business plan, where comparable customers pay $18,000. The $6,000 is a comparison, not a forecast. (The numbers are illustrative.)
03DecisionDecide whether there's a move worth making now
Leave it alone if any of these hold (defaults):
- only routine pages, or the read didn't meet the rule above
- no named reader – company-level traffic from an IP lookup doesn't count
- a risk read from an account at or above the benchmark, with no other warning signs – record it and recheck next week
- an open deal, a renewal in procurement or a recorded budget cut already covers it – add the pages to that record instead
- a move on this account in the last 30 days
Everything else picks a move.
04ActionLeave it alone, and write down why
Set Recommended move to No move, write the reason in one line, and set Review date four weeks out (default). A second week of risk reads brings it back for a fresh look. Leave it alone has the full method.
05DecisionPick the move the read points to
- Growth: a growth read, usage at 80% or more of the benchmark (default), and the feature isn't on their plan. Expansion note.
- Help: everything else that got this far – a risk read from an account below the benchmark, or a growth read from an account under 80% or for something already on their plan. Help offer.
If the account's gap to the benchmark is also widening, add the pages to the churn-risk save instead, or to the renewal play when renewal is inside 90 days.
06ActionAdd an expansion note for the AE
The note below goes on the HubSpot record. The AE runs it the way the PQL handoff runs an upgrade; for add-ons or seats, see the seat and add-on play.
07ActionDraft a help offer for the job they're reading about
Offer help with the task. Never quote the pages back to them. A team exporting data may be building a report, consolidating tools or leaving; a short conversation tells you which, while it's still a conversation.
08Human stepYour team decides and runs the move
The AE or CSM reads the evidence and runs it as drafted, changes it, or passes. Before acting, record the success measure and the review date (default: eight weeks on). A call booked is progress; a paid upgrade, or the account back at the benchmark, is the result. At first the owner sends each help offer from the task. Once the offers have been right for a few weeks, your team can choose to have a HubSpot workflow send them; the record shows what went out.
09OutcomeReview what changed, then sharpen the page groups
On the review date, record three answers: did the move happen, did billing or usage change, and what else played a part? If nothing moved, change the move, stop it, or give it time – the eight-week review has the method. Each quarter, check which page groups came before real moves. Pages that never do go back to routine.
Setup and templates
Sources: page views from Mintlify's Segment integration, tied to the
reader's user ID. Mintlify doesn't identify readers on its own. Readers
sign in to your docs (Mintlify authentication, if your plan includes it),
and a small script in your docs sends Segment the signed-in user. Never
put user IDs in docs links. Each page view is matched to the company
through the user's ID and the group calls your app already sends to
Segment. Names and roles come from the matching CRM contact. Using
RudderStack? Mintlify has no built-in RudderStack integration. Load
RudderStack's snippet from a .js file in your docs folder.
Usage against the benchmark comes from a weekly saved query in PostHog, Amplitude or Mixpanel. Account-level numbers need your analytics tool's account add-on (group analytics in PostHog, Accounts in Amplitude, Group Analytics in Mixpanel) and a group call in your app. Save the query, then subscribe to it (in Amplitude, add it to a dashboard and subscribe to that) so the result lands in your inbox or Slack each week. Plan, ARR, deals and notes come from the CRM. By hand: once a week, export docs page views by user from your product analytics (turn on Mintlify's PostHog, Amplitude or Mixpanel integration first, with readers signed in), tag each page's group in a sheet, and add each account's usage, plan and ARR.
Privacy: your privacy notice should say you track docs reading by person, and that it informs support and sales follow-up. Where the law requires consent (readers in the EU and UK, for example), get it before this tracking starts, and stop when someone withdraws it. Signing in isn't consent. Record the lawful basis, how long you keep the page views, and your processor terms with Mintlify and Segment. Delete or anonymize named page views once the play no longer needs them.
Company properties in HubSpot (Starter or above; free HubSpot allows 10 custom properties in total), or your CRM's account object:
| Property | Type | Filled by |
|---|---|---|
| Docs read type | Dropdown select: Growth · Risk · Routine | Weekly check |
| Docs pages read | Multi-line text (pages and dates) | Weekly check |
| Docs readers | Multi-line text (names and roles) | Weekly check |
| Usage vs benchmark | Number (%) | Weekly check |
| Gap value | Number (currency; next plan's price minus today's ARR) | Weekly check |
| Recommended move | Dropdown select: Expansion note · Help offer · No move | Weekly check |
| Move reason | Single-line text | Weekly check |
| Success measure | Single-line text | Account owner |
| Review date | Date picker | Weekly check, then account owner |
| Review result | Dropdown select: Bought · Back at benchmark · Talked, no change · Stopped | Account owner |
The automation here uses HubSpot workflows (any Professional hub). On Free or Starter, run the same saved view and create the tasks by hand. The weekly list is a saved view: Recommended move is known and Review date is this week or overdue. In HubSpot that's two filter groups: Review date is This week, or Review date is before Today. Each move creates a task for the owner, "Docs read: [move]", with the draft in the body.
Apply these checks to marketing emails sent by hand or automatically: permission to send, accurate sender details, required address information, an easy unsubscribe and shared suppression checks. Keep required service notices separate from marketing.
Automatic sends from HubSpot need a workflow: a marketing email (Marketing Hub Professional) or a sequence from the owner (Sales Hub Enterprise). On Salesforce, the emails need Sales Engagement (included in Unlimited, a paid add-on otherwise), or send them from Customer.io. On Pipedrive, sequences run on deals, so enroll the account's renewal deal.
Expansion note (Growth): [readers and roles] read [pages] in the week of [date] · they're on [plan]; [feature] is on [next plan or add-on] at [price difference] · usage is [x]% of the benchmark · suggested opener:
Hi [name] – teams building [integration or use] on [product] often want a working example. Want me to set one up against your account, and show what [next plan] adds?
Use the "teams building … often" line only if your records support that comparison. Otherwise, describe this account's activity.
Help offer (Help):
Hi [name] – a quick check-in on [team]'s work in [product]. If you're working on [job, such as a report or a change to your setup], I'm happy to spend twenty minutes on it with you.
No move: "No move – [reason]. Recheck [date]."
How Accoil fits
Accoil is a customer-success consultancy with our own tooling, and this is a play we run with you, not for you. We build the benchmark and the page groups with your team, and you approve them. Every week we check every account in the agreed segment, and the recommended move and its evidence, docs reads included, land on the account record in your CRM – we recommend HubSpot – at a pace your team can actually run. Your team makes every call. Nobody from Accoil contacts your customers. After the agreed window we review what changed together, and you keep the playbook, the benchmark and the analysis.
Running it yourself? Swap Segment for RudderStack and HubSpot for Salesforce or Pipedrive. The play stays the same. On Salesforce, the field writes need API access (Enterprise and up, or an add-on on Professional). On Pipedrive, automations and date triggers need the Growth plan.
Thirty minutes with Kate, Simon or Peter on one example segment: what a successful customer looks like, where the gaps are, and whether there's work worth doing this quarter.
Talk to a founder →Keep reading
Monday-Morning Account Triage Playbook 2026
Your best customers show you what good looks like. Every Monday, this play compares each account in a segment with that benchmark, ranks what each gap is worth, caps the list at what your team can run, and puts the week's moves on the account records in your CRM: close a gap, grow the upside, or leave it alone with the reason noted.
Expansion Signal to PQL Handoff Playbook 2026
Your customers who upgraded showed you what ready looks like before they asked. This play checks every account against them each week, confirms the records before anyone calls it ready, and puts the move on the account in your CRM: an upgrade conversation for your AE, an in-app prompt your team chose to automate – or no move, with the reason noted.
The Leave-It-Alone Playbook 2026
When the weekly check finds a gap worth a conversation, this play looks for a reason to wait first – a fresh purchase or renewal, a budget or org change, an open blocker, a departed champion. If the records show one, the reason goes on the CRM record with a date to look again, so the conversation happens when it can land.
Every playbook, one download
All 32 workflows as print-ready playbooks — diagrams included. Plus every new workflow as we publish it.