SEO for developer tools: docs, comparisons, and the error message

Build for four intents: task, comparison, alternative and error. Those are the searches that bring buyers to a developer tool.

• Task: “how to add auth in Next.js”, “Kafka consumer retry logic”. Ship one guide per job in /docs/guides/. Put the answer first, with code.
• Comparison: “X vs Y”. Ship /compare/x-vs-y with a clear table and trade offs. Link from both products’ names in your docs.
• Alternative: “X alternatives”. Ship /alternatives/x with 5 to 10 options, what fits when, and where yours is not a fit.
• Error: the exact message. Ship /docs/errors/<slug> with cause, fix and a copyable snippet.

Name pages in the user’s words. If they search “oauth callback mismatch”, your page title is that phrase, not your internal term.

A fixed page example: /docs/errors/oauth-callback-mismatch. H1: “OAuth callback mismatch”. First line: why it happens. Then the fix in 3 steps.

Docs rank and are what assistants cite. Treat /docs as the product. Structure it so humans and crawlers can read and quote it.

1. 1

   Answer first

   Start each doc with one or two sentences that state the point, limits and version. Then give the minimal code that works.

2. 2

   Keep code in HTML

   Render code blocks server side. Do not hide main content behind client JavaScript. Keep your guide in the HTML, not just the DOM after hydration.

3. 3

   One task per URL

   A page for “JWT refresh tokens”. Another for “JWT rotation in NextAuth”. Do not mix several tasks on one long page.

4. 4

   Version canonicals

   If you host /v1/ and /v2/, add a canonical to the latest stable. Keep older versions indexable only when they still serve users.

5. 5

   Stable names

   Use consistent names for the product, API and methods. Assistants quote exact strings. Avoid renaming endpoints every quarter.

• Add an llms.txt at /llms.txt to state what assistants may read and cite.
• Add a search that works without JavaScript so crawlers can follow results.
• Link each guide to the API reference it uses. Cross link from API to guides.
• Keep examples runnable. A small repo per guide beats a gist you never test.
• Put limits and prices where relevant. Assistants quote that line to users.

Developers run “X vs Y” before they install. They also search for alternatives when they hit a limit. You need both kinds of pages early.

Worked example: /compare/yourtool-vs-auth0. Table rows: protocols, frameworks, self host, rate limits, pricing unit, SOC2. A short verdict per use case.

• Name rivals users already ask about. If they search “yourtool vs keycloak”, use that slug.
• Link from docs pages where a choice appears. For example, from /docs/sso/ to /compare/yourtool-vs-auth0.
• Include screenshots sized for mobile and desktop. Keep alt text clear for what it shows.
• Keep tables as HTML. Assistants quote rows verbatim when cells are simple.

Stack Overflow answers and Hacker News threads rank on problems. You can win that intent with an error library inside your docs.

1. 1

   Collect real errors

   Parse your logs. Add the top 50 messages to a backlog. Keep the original string in the H1 and title.

2. 2

   Write minimal fixes

   Cause, fix, snippet. Show for two stacks if your users split, for example Node and Python.

3. 3

   Cross link

   Link each error to the guide that prevents it, and to the API reference that throws it.

4. 4

   Add a catch all

   Ship /docs/errors/ with a list, a search box and tags for product area.

Example: /docs/errors/invalid-grant. Explain why refresh tokens fail. Show the exact curl that proves the state. Add a test users run locally.

GitHub READMEs and package registries rank on the tool’s name. Many users start there. Treat them as entry points, not mirrors.

• README: first sentence says what it is and is not. Add a link to /docs/getting-started and /compare/yourtool-vs-x.
• README: show a minimal example in 10 lines. Keep install, quickstart, links. Move long prose to docs.
• Package pages: fill metadata. npm description, keywords, repository, homepage. The same for PyPI, crates.io, Docker Hub.
• Tag releases in git and publish to the registry on release. Link to /changelog for details.
• Use topics and labels users search for. For example, oidc, sso, oauth2, saml2.

A cleaned README reduces support load. It also helps assistants quote the right use case when they fetch your repo page for a user’s question.

A dated changelog and a real integrations section pull steady search. They also show your pace to buyers and to assistants.

• /changelog: one entry per release with a date and links to new docs. Keep titles like “Add SAML IdP for Okta” rather than “Improvements”.
• /integrations: one index page and a page per integration. For example, /integrations/okta, /integrations/nextauth.
• Each integration page: what it does, limits, a 60 second setup, and links to code examples.
• Link both ways. From docs to the integration page and from the integration page to the exact guide.
• These pages catch “X + Y” searches and let others link to a specific setup.

Generative engine optimisation is about being named and cited in AI answers. For a dev tool, that means clear, quotable pages and crawl access.

• Allow answering crawlers. Do not block Googlebot, Bingbot, OAI-SearchBot, Claude-SearchBot, PerplexityBot, or Applebot if you want to be cited.
• Keep stable, scannable structures. Lists, tables and short summaries get quoted more often than prose walls.
• Be where answers already cite. Get listed on comparison pages and directories in your space. Provide a one line description others can paste.
• Ship a page that states what the product does and does not do, with limits and prices. Assistants lift this line in answers.
• Measure weekly. Ask assistants the questions your buyer asks and note who they name. Track gains and losses per query.

AI crawlers read your docs. Keep content in HTML. Expose a clean sitemap. Add an llms.txt to make your intent clear to model vendors as of 2026.

Treat performance and crawlability as table stakes. Slow, client only docs lose users and fail to rank for hard queries.

• Aim for LCP under 2.5 seconds, CLS under 0.1 and INP under 200 ms on docs templates.
• Server render docs pages. Hydrate enhancements only. Avoid blocking scripts. Split bundles and pre render code tabs.
• Use clean URLs. /docs/getting-started, not /docs.php?id=page. Keep the path stable across versions.
• Add internal links from each doc to related tasks and to the API reference. Link back to /docs/ and to /pricing where it fits.
• Add SoftwareApplication schema to your homepage. Add HowTo or FAQ schema only where the page matches the type.
• Set canonicals for versioned docs and for mirrored content. Avoid index bloat from duplicate paths.
• Check Search Console for index coverage and Core Web Vitals. Fix the pages shown but never clicked by improving titles.

A fixed template example: a left nav, a single H1, a summary box, code blocks with copy buttons, and a related links section below the fold.

You do not need a big budget. You do need a few good links and pages that match intent. Start with the channels developers already read.

• Launch for links and feedback. Ship a post with a clear title and a link to /docs/getting-started. Submit to Product Hunt, Hacker News and Indie Hackers.
• Answer questions where you have expertise. Link only when your page answers the question. Think Stack Overflow and relevant GitHub issues.
• Publish one page per pain the product solves. For example, /use-cases/jwt-rotation, /use-cases/sso-for-internal-tools.
• Ask early users to add your tool to their README and blog posts. Offer a setup gist they can embed.
• Use Search Console to see which tasks and errors get impressions. Write the next page to match that demand.

A lean plan: week 1 write /docs/getting-started and one task page. Week 2 ship one comparison page. Week 3 add two error pages and /changelog.