Technical SEO for Developer Tools Companies

A documentation set is not authored page by page. It is generated. Somebody writes a Markdown file in a repository and a build step turns it into HTML. The next release publishes the whole set again under a new path. The API reference is further down the same road. One page per endpoint, straight out of an OpenAPI file or a docstring pass. Nobody reads it end to end.

That is where the technical work is on this kind of site. The marketing pages are a rounding error next to the docs, and the docs behave like a database with a renderer bolted on.

Versions multiply every page you have

A tool with nine releases and a version selector can serve nine copies of Installation, nine copies of Configuration and nine copies of every guide. A search engine sees near-duplicates. You see a support obligation, because customers on the old major version need those pages to keep working.

The reflex answer is to canonicalise every version to the current one and leave the rest crawlable. That is right often enough to be a starting point and wrong often enough to check. Where the old version genuinely documents a different API, a canonical does harm. It sends a reader to instructions that do not work on the release they have installed. We go through it version by version. Which paths are stable aliases, which are frozen snapshots, what the version selector puts in the HTML. And whether the sitemap agrees with any of it.

The generated reference is a templated page set on your domain

One page per endpoint, built from a schema, is exactly the shape Google’s scaled content abuse policy describes. We treat that policy as a site-wide risk. The reference is legitimate. It also has to look legitimate to a crawler that cannot read your intent.

What separates a useful reference page from filler is everything the schema does not contain. A real request and the real response it returns. The errors this endpoint produces and what causes each one. The call you make before it and the one you make after. Rate limits. A line about what changed in the last major version. A page with none of that is a table of parameter names, and there is no argument for indexing it separately from its neighbours.

Your docs are on a different hostname from the thing you sell

To a search engine, docs.example.com and example.com are two sites. A reverse proxy serving example.com/docs is one. That choice normally gets made by whoever set the docs platform up, on a Tuesday, for deployment reasons. It then decides how authority moves between the pages that sell the product and the pages that get the traffic.

We are not going to ask you to move a working docs deployment for the sake of a link graph. We will tell you what the current arrangement costs and what the internal linking has to do to make up for it. And which Search Console property you have been reading your numbers out of, while the other one held the visits.

The registries publish your README as their own page

npm, PyPI, crates.io, Packagist and pkg.go.dev each render your README on a page they own. The domain is older and stronger than yours. So does the repository page, and so do the mirrors that scrape it. There is no canonical you can set on somebody else’s site.

What you can decide is what each surface is for. A README that answers what this is, how to install it and where the docs are will lose the long-tail queries to your own documentation. That is the outcome you want. A README that contains the whole manual makes the registry page the better result, and it wins.

Where the ranking is not worth chasing

A developer pasting an error message into a search box wants a thread with the same stack trace in it. A developer asking how to do a thing with your library wants your docs. We take the second job seriously as a target and leave the first one alone. Writing a page to outrank an issue thread about a bug you already fixed is effort with nobody waiting at the end of it.