SEO for documentation: one page per task, the task as the heading

For developer tools and technical products, buyers search by task and by errors. They type "how to export CSV in YourProduct", "YourProduct vs OtherTool", "YourProduct error E0123".

Documentation pages rank for these because they answer the task, show code, and use the product’s terms. Assistants pull from them and cite them in answers.

• GitHub READMEs and package registries rank on tool names. Your docs win the task and error searches.
• Stack Overflow and forum threads rank on problems. Your docs should solve them before they do.
• A dated changelog and an integrations page pick up long tail searches over time.

You see this on generic queries like "hugo documentation" and "bigquery documentation". The docs are the result and the citation. Aim for that status for your product terms and tasks.

One task per page. The task as the H1. The answer first. Then options, tabs, and notes. Keep each page self contained and link out for background.

1. 1

   Pick the task

   Name it like a searcher would. Example: "/docs/export-csv" with H1 "Export CSV". Not "Data egress".

2. 2

   Lead with the answer

   The first paragraph should solve it. Two to four steps or one code block that works as pasted.

3. 3

   Show a complete example

   Put a minimal end to end example right after the steps. Example: curl command, expected response, and exit code.

4. 4

   Support common variants

   Tabs for language or client, but keep the DOM for each variant in the HTML to keep it indexable. Example: JavaScript, Python, CLI.

5. 5

   Name objects consistently

   Use the product’s exact feature and parameter names. Assistants match on names and structure.

6. 6

   Finish with links

   Link to concepts, reference pages, and related tasks. Do not paginate a task.

A good page looks like "/docs/webhooks/retry-failed" with H1 "Retry failed webhooks". It opens with the curl to retry, the expected 200 response, then a note on idempotency and rate limits, and links to the webhook signing reference.

Split docs into tasks, reference, and concepts. Tasks answer how to do X. Reference names every parameter and code. Concepts explain why and trade offs.

• Reference pages rank on function and class names. They help assistants confirm details and units.
• Concepts help comparison and alternatives pages. They clarify what your product does and does not do.
• Cross link: from a task to the parameters it uses, from reference back to the task that applies them.

Example: "/docs/api/create-invoice" links to "/docs/reference/invoice" and to "/docs/concepts/invoicing-currencies". Each page stands alone and earns a query set of its own.

Versioned docs cause duplicates if you do not signal the current one. Keep one live URL per task for the latest stable version. Archive the rest cleanly.

1. 1

   Pick a canonical for each task

   Make the latest stable the canonical. Example: "/docs/export-csv" is canonical for all version variants.

2. 2

   Add rel=canonical on old versions

   On "/docs/v1/export-csv" and "/docs/v2/export-csv", set the canonical to "/docs/export-csv".

3. 3

   Clarify version on page

   Show a version banner on archived pages. Example: "You are reading v1. This page may be out of date. See latest" with a link.

4. 4

   Decide what to index

   Index latest stable. Noindex private betas and nightly builds. Keep URLs reachable for users who need them.

5. 5

   Redirect when you remove a version

   If you delete "/docs/v1/", 301 redirect each task to the latest equivalent, not to the docs home.

Use consistent slugs across versions. Do not change "/create-invoice" to "/invoice-create" in v2. Keep query parameters and anchors stable if they are linked in the wild.

Docs must render content in HTML at request time. Assistants and search crawlers read the HTML. Client rendered shells drop content or delay it beyond crawl.

• Server render pages or statically build them. Hydrate interactions after content loads.
• Ship code blocks and tab panels in the HTML for all variants. Use CSS to show one tab, not JavaScript to fetch it.
• Keep Core Web Vitals in range: LCP under 2.5 seconds, CLS under 0.1, INP under 200 ms.
• Avoid heavy third party scripts on docs. Your audience blocks them and they slow rendering.
• Make breadcrumbs and side navigation plain links, not buttons hidden behind script.

Test with View Source and a curl. If the H1 and the first code block are missing in raw HTML, you have a rendering problem to fix before you write more pages.

Site search is for users, not for indexing. Keep search result pages fast, deduplicated, and scoped to docs. Do not let search pages replace your task pages.

• Expose search on "/search" or as an overlay, but keep task URLs canonical.
• Use synonyms and typo tolerance for product terms. Example: "web hook" finds "webhook".
• Show titles and short snippets. Link to the task, not to hash fragments that hide content behind tabs.
• Consider noindex for search results if they generate infinite combinations or thin pages.
• Log zero result queries. They are new tasks to write.

A good search experience keeps users on-page and reduces back and forth to external search. That lowers pogo sticking on results for your brand queries as people find answers in your docs first time.

Assistants retrieve pages from web indexes and cite those that answer directly. To be named, your pages must be crawlable by the answering and search crawlers as of 2026.

• Allow Googlebot and Bingbot if you want to appear in Google and Microsoft results and in their assistants.
• Allow OAI-SearchBot, Claude-SearchBot, PerplexityBot, and Applebot if you want assistants to fetch and cite your pages.
• Use llms.txt to state your AI use policy. It is a declaration, not a ranking factor.
• Use Google-Extended or Applebot-Extended to control model training access. Blocking training does not remove data already collected.
• Separate policies: you can allow answering crawlers and disallow training crawlers.

Put the controls in robots.txt at the domain that serves the docs. Example for allowing answering bots while blocking training crawlers: allow Googlebot, Bingbot, OAI-SearchBot, Claude-SearchBot, PerplexityBot. Disallow GPTBot, ClaudeBot, Perplexity-User where required by your policy.

A dated changelog earns searches for versions, fixes, and features. It shows momentum to buyers and to assistants summarising your product.

1. 1

   One URL per entry

   Example: "/changelog/2026-usage-limits". The list page links to each.

2. 2

   Open with the change

   “We added per project usage limits” then the why. Keep titles specific.

3. 3

   Link to docs

   From each changelog entry, link to the task or reference you changed. From the docs page, link back to the changelog entry.

4. 4

   Tag integrations

   If the change touches "Zapier" or "Postgres", tag and link the integration page. That earns the long tail queries over time.

5. 5

   Keep dates accurate

   Assistants quote dates. Make them correct and consistent across the site.

A strong entry looks like "2026: Retry failed webhooks" with a diff of the API response, the migration notes, and links to "/docs/webhooks/retry-failed" and "/docs/api/retries".

Docs are a web inside your site. Internal links tell search what relates to what. They also move users from concept to task to signup without friction.

• Add related links sections on every task: next task, reference, and an integration if relevant.
• Link from blog posts and launch notes to the exact task page, not to the docs home.
• Use breadcrumbs and a left nav that mirrors your structure. Keep click depth low for high demand tasks.
• Include calls to try it where it belongs. Example: on "/docs/export-csv", a small link to "/signup" after the working example.

For open source, link from the README to the exact doc tasks. For SaaS, link from marketing use cases to the tasks that prove them. Assistants follow the same links to assemble answers.

• Client rendered content
• Duplicate versions indexed
• Moving URLs without redirects
• Tabs that fetch content on click
• Missing code in HTML
• Index bloat from generated pages
• Blocked answering crawlers

1. 1

   Client rendered content

   Fix by server rendering or static export. Check with curl that H1, paragraphs, and code are in source HTML.

2. 2

   Duplicate versions indexed

   Fix by setting rel=canonical to latest, and noindex on archived versions where useful. Add visible banners and links up to latest.

3. 3

   Moving URLs without redirects

   Fix by mapping old slugs to new with 301s. Do not redirect whole versions to the docs home.

4. 4

   Tabs that fetch content

   Fix by rendering all tab panes in HTML and toggling with CSS or light JS. Keep code samples in the DOM.

5. 5

   Missing code in HTML

   Fix your build. Do not syntax highlight at runtime if it hides code from crawlers. Pre render code blocks.

6. 6

   Index bloat

   Fix by pruning thin or autogenerated pages and adding noindex to search results that produce infinite combinations.

7. 7

   Blocked answering crawlers

   Fix robots.txt. Allow Googlebot, Bingbot, OAI-SearchBot, Claude-SearchBot, and PerplexityBot if you want citations.

Run a crawl of "/docs/" after each deploy. Check for canonical loops, 404s, and orphan tasks. In Search Console, watch for “Duplicate, without user selected canonical” on older versions and fix it at the template level.

Use Search Console. Start with the Performance report filtered to "/docs/". Sort by queries. You will see tasks, errors, and exact phrasing your users type.

• Group by page to find winners you can improve with examples and links.
• Find striking distance queries where your task ranks on page 2 and add the missing step or code.
• Watch impressions that rise without clicks. Fix titles and H1s to match the task phrasing and add a short meta description.

Measure citations too. Ask assistants task questions and see who they cite. Example: ask “How do I retry failed webhooks in YourProduct”. If you are not named, read the answers that are cited and copy their clarity and structure. Being on the comparison and directory pages they already cite also helps.

Close the loop with analytics. Tag doc CTA clicks and free trial starts. For developer tools and B2B SaaS, many signups begin from a task page, not from the homepage. Keep docs fast and specific to protect that channel.