Dev.to WebDev 🛠 Dev Tue, 10 Nov 2026 10:20:30 +0000 👁 0 📖 4 min read

What I'd do differently with SEO on a developer documentation site (versions, search and all)

Here's a pattern I've seen more than once. A developer searches for how to do something with a library. The top result is the library's own documentation, which is good. But it's the documentation for version 1, three major versions ago, with an API that no longer exists. They copy the code, it fails, and they conclude the library is broken.

Documentation sites often get more search traffic than the rest of a product's website combined. They're also usually built by engineers, in a docs framework, with SEO left to the defaults. If I were setting one up again, these are the decisions I'd make on purpose.

1. Decide what "the canonical version" means, before you have two

The single biggest docs SEO problem is versioning. When you publish v2 docs alongside v1, you suddenly have two pages for every topic, often nearly identical. Search engines have to pick one, and they don't always pick the current one.

I'd decide on day one:

A stable "latest" URL for each page, such as /docs/latest/auth or simply /docs/auth, which always shows the current version.
Versioned URLs for older docs, such as /docs/v1/auth.
Canonicals from older versions to the latest equivalent, where the page is substantially the same. Where a page is genuinely different, because the API changed, a self-canonical with a clear "you're viewing old docs" banner may be better.

Whatever you choose, apply it consistently. Mixed approaches across versions are what confuse search engines most.

2. Show a version banner and link to the current page

Every old-version page should say, at the top, "You're viewing documentation for v1. [See the latest version of this page]." Link to the equivalent page, not the docs homepage. This helps visitors who land on old pages from search, and those internal links reinforce which version you consider current.

3. Don't let every version be equally linked

If the navigation on every page links to every version of every page, crawlers spend as much time on v1 as on the current docs. I'd make the sidebar link only within the current version, with a version switcher that's a dropdown or form control rather than hundreds of crawlable links on every page.

4. Give every page a specific title

Docs frameworks often generate titles like "Authentication | Docs" or, worse, "Docs" on every page. But developers search for specific tasks: "how to refresh an access token in [library]".

I'd write titles that include the product name and the task: "Refresh access tokens – [Product] docs". It's the single most impactful change for how docs pages appear in search results.

5. Write the first paragraph for the person who just arrived from search

Many docs pages assume you've read the previous page. Visitors from search haven't. I'd start each page with one or two sentences saying what it covers and when you'd need it, before any prerequisites or code.

That paragraph also tends to become the snippet shown in results, so it's worth writing deliberately rather than leaving it to whatever text comes first.

6. Keep the URLs when you reorganise

Docs get reorganised often: new sections, renamed concepts, merged pages. Each reorganisation breaks links from Stack Overflow answers, blog posts, tutorials and the product itself.

I'd treat the URL list as a public interface:

Every moved page gets a redirect from its old URL to its new one.
Redirects are kept in the repository, reviewed and never deleted.
A build check fails if a previously published URL disappears without a redirect.

# compare last release's URL list with this build's
comm -23 <(sort urls-previous.txt) <(sort urls-current.txt) > missing.txt
[ -s missing.txt ] && { echo "URLs removed without redirect:"; cat missing.txt; exit 1; }

(The real check should also exclude URLs that now have a redirect configured.)

7. Make sure the content is in the HTML

Some docs setups render pages client-side, loading content with JavaScript after the page shell arrives. Search engines can often render JavaScript, but it adds delay and fragility. Most popular docs frameworks can produce static HTML at build time. I'd confirm that the main content, code samples included, is present in the initial HTML.

8. Watch which version search engines actually send people to

Finally, I'd look at Search Console regularly with one question: which version are visitors landing on? If a large share of search traffic arrives on old versions, the canonical and linking setup isn't working, and those visitors are getting outdated instructions.

A simple query on your landing page data, grouping by the version segment of the URL, makes this visible in a few minutes.

What I'd skip

Keyword stuffing pages with every synonym. Developers search with precise terms. Use the terms they'd use, naturally.
Separate "SEO landing pages" duplicating docs content. The docs page itself is usually the best answer.
Indexing every search-results page from the docs' own search. These create endless low-value URLs.

The short version

Decide your versioning and canonical strategy before v2 ships, write specific titles and first paragraphs, treat docs URLs as a public interface, and check which version search actually sends people to.

Catching the moment old docs start outranking new ones is exactly the kind of quiet regression seotto.com watches for.