Discussion starter: a B2B and SaaS SEO question, posted with an answer from Niraj Raut to open the thread. If you have dealt with this on a site, reply with what you saw, especially where it differs.
- SaaS SEO
Docs pages outrank marketing pages for high-intent product queries. Do you optimise docs for conversion, or push those queries to marketing pages?
Disclosure: Niraj Raut, who posted this answer, runs the SEO consultancy linked at the end of it.
1 reply
-
adminAdmin
The short answer is to read the docs ranking as evidence about intent before treating it as a problem. For queries about a specific capability, limit or setup (“[product] SAML SSO”, “[product] API rate limits”, “[product] Salesforce integration”), I would make the docs convert and leave them ranking. For buying questions (pricing, plans, comparisons, alternatives), the marketing page should own the result, and docs winning there is a sign the marketing page is too vague to compete. Unbranded category queries sit in between, and the results page shows which type of page Google wants for them.
The main qualification is who is searching. Traffic that looks high-intent can mix prospects evaluating the product with existing customers halfway through an implementation, and that mix changes what conversion should mean on the page. Before redesigning anything, measure what share of docs landings come from logged-in users or known customer accounts.
What I would not do is force a swap with canonical tags, noindex or redirects. Those tools are built for duplicates and removals, not for choosing between two different pages, and they can take your ranking page out of the results with no guarantee Google accepts the substitute.
Why Google is choosing the docs page
A capability query carries three questions: is it supported, on which plan, and how does it work. If the SSO docs page lists the supported protocols, provisioning options, limits and setup steps, while the security page says “enterprise-grade security”, Google is choosing the page that answers the question. Docs can also carry dense internal linking and earn links from forums, integration partners and developer communities, signals a feature page does not get by default.
Your docs and marketing pages are also competing for the same slots. When Google announced its site diversity change in 2019, it said you usually won’t see more than two listings from the same site in top results, with exceptions where its systems judge more to be especially relevant, and that it would generally treat subdomains as part of the root domain, while treating them as separate sites when deemed relevant. Hosting docs on a subdomain does not reliably create extra room, and a marketing page that starts ranking may replace the docs listing rather than join it. Plan for one or two of your URLs on that results page, and decide which should lead.
Sort the queries before choosing a page
Query pattern Likely searcher What they need answered Page that should own it [product] + capability (SSO, SCIM, webhooks, audit logs, rate limits) Evaluator in IT, security or engineering, or an admin setting it up Supported or not, which plan, how it works Docs, with plan and next-step modules, linked to the feature page [product] pricing, plans, enterprise Buyer or budget holder Cost, limits per plan, contract terms Pricing page [product] vs [competitor], [competitor] alternative Evaluator comparing a shortlist Differences that matter to them, migration effort Comparison page, linking to docs for proof [category] with [capability], unbranded Early evaluator Which vendors do this, and how well Whichever page type the results page rewards How to [task] in [product], error messages Existing user Steps and fixes Docs; conversion here means adoption and expansion The unbranded row is where the results page decides. Look at what ranks for that query class across your competitors. If Google shows competitors’ docs, GitHub repositories and forum threads, a marketing page is fighting the intent Google has inferred. If it shows landing pages and comparison articles, your docs are ranking despite a mismatch, and a stronger marketing page has a realistic chance.
Making docs convert without breaking them
- Plan availability at the top of capability pages (“Available on Business and Enterprise”), linked to pricing. It answers the evaluator’s second question and helps customers too.
- A two-sentence summary for evaluators before the setup steps: what the feature does and who it is for.
- One next step matched to the page’s task: “Try this in a free workspace” on a feature guide, “Get an API key” on an API reference, “Talk to us about SSO” on an enterprise-only capability. One, not five.
- Descriptive links to the feature, security and pricing pages. Google’s link guidance asks for anchor text that is descriptive, reasonably concise and relevant, which also tells an evaluator where the link goes.
- No pop-ups, gates or hero banners. A docs page that reads like an ad works against the specificity that made it rank.
- Instrumentation: docs-sourced signups, docs-to-pricing paths and docs pages as touches on opportunities in the CRM, tracked alongside docs health signals such as page feedback and support tickets on the same topic.
Ownership matters as much as copy. Agree with the docs team that conversion modules are template components they approve, not text that marketing inserts into their pages. That keeps the modules consistent and stops them spreading to pages where they do not fit, such as error references and changelogs.
Pushing a query to a marketing page: what works and what backfires
What works is making the marketing page deserve the query: named capabilities, supported standards, limits, a plan table, screenshots, a short configuration or code example, proof such as certifications, and a clear link to the docs for full detail. Match the title and main heading to the evaluative question, and link both ways between the docs and the marketing page with descriptive anchors.
What backfires is using index controls to force the outcome. Google’s canonicalisation guidance is framed around duplicate content, and a setup guide and a feature page are different documents; declaring one the canonical of the other asks Google to fold away the page that answers the question. Noindex is blunter. The same guidance says: “We don’t recommend using noindex to prevent selection of a canonical page within a single site, because it will completely block the page from Search.” Redirecting docs to marketing pages breaks them for the customers who need the instructions.
No change guarantees that Google swaps the pages. It may rank a competitor’s docs instead of your marketing page, so measure at the level of the query group across both URLs, not the marketing page alone.
Evidence to check before deciding
- Query-level Search Console data for docs URLs, bucketed with regex into capability, pricing, comparison, how-to and error queries, and split into branded and unbranded.
- Whether the marketing page ranks at all for those queries. If docs sit at 3 and the marketing page at 40, Google is not weighing them closely. If both appear for the same queries and trade places over time, they are splitting the intent and need clearer separation.
- Who lands: the share of docs landing sessions from logged-in users or known customer accounts.
- Conversion paths from docs landings: signups within the session or a set window, and docs pages appearing among opportunity touchpoints. Compare with care. Docs visitors may be further into evaluation than marketing-page visitors, so a higher docs conversion rate does not prove the docs page persuades better.
- The results page for each bucket, which shows what intent Google has inferred.
Worked example: an SSO guide that never mentions the plan
Hypothetical example:
A B2B scheduling SaaS finds its SSO setup guide ranking first for “[brand] SSO” and “[brand] SAML”, with about 1,100 landings a month, while its Security page sits on page two. Product analytics show about 650 of those landings are logged-in admins configuring SSO. The other 450 are anonymous, and almost none of them sign up or contact sales, because the guide never says SSO requires the Enterprise plan.
The team adds an “Available on Enterprise” label linked to pricing, a “Talk to us about SSO” button and a two-sentence summary for evaluators. It also rewrites the Security page with protocol, SCIM and audit log details and links it to the guide. Success is judged on the SSO query group across both URLs: combined clicks hold or rise, enterprise enquiries from those landings rise, and the admins’ experience does not get worse, measured through page feedback and support tickets about SSO setup.
How to test it, and what would change the decision
The docs modules are a conversion test more than an SEO test: split users on the docs template with your testing tool, and treat rankings on the tested pages as a guardrail. B2B conversion volumes are low, so set the test length by conversions rather than by weeks. Estimate how long the tested pages need to produce enough signups or enquiries to detect the lift you care about, and run that long.
The marketing-page push is a before-and-after test on a query group. If combined clicks for the group fall after the change, Google has declined the swap: roll back the title and internal link changes and put the effort into the docs route. If the marketing page takes the lead listing and combined clicks and enquiries hold or rise, extend the approach to similar query groups.
Two results would change my default. If the docs modules lift signups but page feedback and support tickets show customers finding the docs harder to use, scale the modules back to capability pages only. If capability queries turn out to come mostly from existing customers, stop counting trials on those pages and measure feature adoption instead.
The practical position
Let the query decide which page owns it, make every page Google chooses capable of the next step, and measure the query group rather than the URL. A docs page ranking for “[product] SSO” is not taking traffic from a marketing page; it is answering the question Google thinks the searcher asked. The job is to make sure that answer also tells a prospect how to buy it.
Need help with this on your own site?
Niraj Raut works with businesses in Nepal, Australia, the UK, Europe and the US on technical SEO, ecommerce SEO, local SEO and AI search.
Add a reply Cancel reply
Replies are open to approved members. Log in or apply to join.