Should Documentation Live on a Subdomain or a Subdirectory?

By the time you finish you will have picked one of docs.example.com or example.com/docs on grounds you can state out loud, and you will know which parts of that decision rest on documented behaviour and which rest on inference. The distinction matters here more than in most SEO decisions, because this particular question attracts confident claims that nobody can demonstrate.

Before you start

Find out what your infrastructure can serve. If your marketing site is on a platform that cannot proxy a path to another origin, a subdirectory is not available to you at any price, and the rest of the argument is academic. Check this first - it resolves the question outright for a large share of teams.

Steps

1. Establish the constraint before the preference.
   A subdirectory requires your main domain to route /docs to wherever the documentation is hosted, usually via a reverse proxy or edge rewrite rule. If that is not possible on your stack, choose the subdomain and move on.

2. Understand what is documented and what is inferred.
   Search engines state publicly that they handle both, and that subdomains and subdirectories can both rank. What practitioners report - that consolidating onto one hostname tends to perform better - is inference from case studies with many uncontrolled variables. Treat it as a mild prior rather than a rule.

3. Weigh the operational cost of each.
   A subdomain needs its own Search Console property, its own analytics view or hostname filter, its own certificate, and its own robots.txt. A subdirectory inherits all of those from the main site but adds a proxy layer that has to be maintained, monitored and kept out of the marketing site's caching rules.

4. Check for path collisions if you choose the subdirectory.
   Confirm nothing already lives at /docs, /help or whatever prefix you pick, including future marketing pages. Reserve the prefix in whatever routing config your main site uses so nobody claims it by accident later.

5. Set canonical tags to the public URL, whichever you choose.
   Proxied documentation frequently remains reachable at its origin hostname as well, which produces two indexable copies. The canonical on every page must point at the public path, and ideally the origin should refuse direct traffic.

6. Link the documentation from your main site's navigation either way.
   Internal links are the mechanism by which crawlers find and weigh the section, and they work across a subdomain boundary as well as within a path. A subdirectory nobody links to has no clear advantage over a subdomain that is linked from every page.

7. Keep the trailing structure clean.
   /docs/getting-started, not /docs/index.php?article=17. This affects reader comprehension and click-through more reliably than the hostname question you started with.

8. Whatever you pick, treat a later change as a migration.
   Full redirect map, both properties verified, and several weeks of watching the index settle. The gain that motivates such a move is rarely large enough to survive its own execution risk.

The subdirectory consolidates authority. The subdomain is far easier to operate.

Common mistakes

Migrating an established docs subdomain for a theoretical uplift. The migration has certain costs - redirects, temporary ranking movement, broken external links - against an inferred benefit. Where the subdomain already ranks, the arithmetic rarely favours moving.

Proxying without setting canonicals. The origin hostname stays crawlable, and now the same articles exist at two URLs. This is the most common way a subdirectory setup ends up worse for search than the subdomain it replaced.

Assuming a subdirectory inherits ranking automatically. Sharing a domain does not make a new section rank. It still needs links, crawl access and content that matches queries, and none of those arrive with the path prefix.

Splitting Search Console properties without noticing. A subdomain reports separately. Teams that forget this conclude documentation traffic collapsed when it merely moved to a property nobody had opened.

Choosing based on a single case study. Published before-and-after results almost always coincide with a redesign, a content rewrite or a replatform, so the hostname change is entangled with three other things and cannot be isolated.

When this stops scaling

As a one-off decision this holds indefinitely, and the setup needs no maintenance beyond whatever the proxy or the certificate requires.

The threshold is surface count. One documentation site behind a rewrite rule is fine. Four - product docs, API reference, changelog, and a status page - each with its own origin and its own proxy rule, is a routing layer, and routing layers acquire edge cases: caching rules that strip headers, a rewrite that breaks pagination, a certificate that renews on a hostname nobody remembers owning.

The second threshold is localisation. Adding language variants multiplies whichever structure you chose and introduces hreflang, which is a genuinely harder problem than the subdomain question and one where getting the URL structure wrong first is expensive to undo.

If most of your effort is going into serving the documentation rather than writing it, that is a signal the hosting decision has become the project. SupportPages serves help centres on your own hostname with the sitemap, canonicals and certificate handled, which removes this class of work without changing the underlying trade-off you have just reasoned through.