# SEO for documentation: one page per task, the task as the heading Docs win technical searches and citations. They are what assistants quote. You get there with one page per task, clear version signals, and pages that render in HTML. This guide gives you the pattern and the traps to avoid. Updated 2026-09-14 · Source: https://porteur.ai/guides/seo-for-documentation ## Why documentation is where you win citations and trials 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. ## The page pattern that ranks and gets cited 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. **Pick the task** Name it like a searcher would. Example: "/docs/export-csv" with H1 "Export CSV". Not "Data egress". 2. **Lead with the answer** The first paragraph should solve it. Two to four steps or one code block that works as pasted. 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. **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. **Name objects consistently** Use the product’s exact feature and parameter names. Assistants match on names and structure. 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. > Keep titles under about 60 characters so search results do not truncate your task names. ## Reference and concepts live beside tasks, not instead of them 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. ## Versions, canonicals and what to publish 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. **Pick a canonical for each task** Make the latest stable the canonical. Example: "/docs/export-csv" is canonical for all version variants. 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. **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. **Decide what to index** Index latest stable. Noindex private betas and nightly builds. Keep URLs reachable for users who need them. 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. ## Performance, HTML output and navigation that crawlers can read 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. ## Search inside the docs that helps users and does not hurt SEO 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. ## llms.txt and robots controls for assistants and training crawlers 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. > Blocking the answering and search crawlers makes your docs invisible to assistants. 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. ## The changelog that earns long tail and proves activity A dated changelog earns searches for versions, fixes, and features. It shows momentum to buyers and to assistants summarising your product. 1. **One URL per entry** Example: "/changelog/2026-usage-limits". The list page links to each. 2. **Open with the change** “We added per project usage limits” then the why. Keep titles specific. 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. **Tag integrations** If the change touches "Zapier" or "Postgres", tag and link the integration page. That earns the long tail queries over time. 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". ## Internal links and navigation that spread equity and intent 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. ## What breaks docs SEO and how to fix it - 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. **Client rendered content** Fix by server rendering or static export. Check with curl that H1, paragraphs, and code are in source HTML. 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. **Moving URLs without redirects** Fix by mapping old slugs to new with 301s. Do not redirect whole versions to the docs home. 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. **Missing code in HTML** Fix your build. Do not syntax highlight at runtime if it hides code from crawlers. Pre render code blocks. 6. **Index bloat** Fix by pruning thin or autogenerated pages and adding noindex to search results that produce infinite combinations. 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. ## Measure, learn, and write the next task 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. ## Questions ### Should I host docs on a subdomain or a subdirectory? Use the structure you can maintain. A subdirectory keeps equity on one host, for example yourproduct.com/docs. A subdomain works if you can keep the same build, analytics, and robots controls. Do not split versions across hosts. ### How do I handle multiple programming languages without hurting SEO? Render all code tabs in the HTML on the same URL. Use tabs to switch the visible block, not to fetch content. Keep the task H1 and intro the same. If a language needs a distinct flow, split it into its own task page and link both ways. ### Should search results pages be indexed? Usually no. They create many thin combinations and can outrank your task pages. Keep them fast and helpful for users. If you must index a few saved searches, set unique titles and descriptions and limit crawl with robots rules on parameters. ### Is a static site generator ok for docs? Yes. Static output is ideal for speed and HTML. Check that your theme renders code blocks and tab panels in the HTML. If you add client search, make sure it does not hide content until JavaScript runs. ### How should I name doc pages for comparison and alternatives? Do not hide them. Ship pages like "/docs/migrate-from-other-tool" and "/docs/compare/feature-flags-vs-ab-tests" if they fit your product. Use neutral language and link from marketing pages. These queries convert on developer tools and B2B SaaS. ### How do I keep old versions available without cannibalising the latest? Keep them live at versioned paths with visible banners. Point rel=canonical to the latest stable. Add noindex where needed. Link forward to the latest task and back only when it helps a maintainer. ## Read next - [llms.txt: what it is, examples, and how to write yours](https://porteur.ai/guides/llms-txt): llms.txt is a Markdown file at /llms.txt that maps your site for language models. See the format, a worked example, and write yours in twenty minutes. - [robots.txt for AI crawlers: GPTBot, ClaudeBot, PerplexityBot and what to allow](https://porteur.ai/guides/robots-txt-for-ai-crawlers): Decide which AI crawlers to allow in robots.txt, why it matters, and copy‑paste examples for GPTBot, ClaudeBot, PerplexityBot, Google‑Extended and more. - [Canonical tags: what they do and the mistakes that cost rankings](https://porteur.ai/guides/canonical-tag): What a canonical tag does, when to use one, the mistakes that cost rankings, and how to check and fix canonicals on a small site. - [Alternate page with proper canonical tag: what Search Console means](https://porteur.ai/guides/alternate-page-with-proper-canonical-tag): What this Search Console status means, when to ignore it, when it hides the wrong page, and the exact checks and fixes to set the right canonical. - [Internal linking for a small site: which pages link to which](https://porteur.ai/guides/internal-linking-for-seo): Decide which pages rank. Build hubs, write clear anchors, fix orphans, and crawl your site to map links you control. - [Core Web Vitals for a product site: the three numbers](https://porteur.ai/guides/core-web-vitals): The product founder’s guide to LCP, CLS and INP: what Google measures, why phones decide the pass, common causes, and how to test and fix. - [SEO for developer tools: docs, comparisons, and the error message](https://porteur.ai/guides/seo-for-developer-tools): Ship docs that rank, pages for comparisons and errors, and get cited by assistants. What to publish on a dev tool site, and how to measure it. Give your docs URL and get a free check in about thirty seconds that reads your site and the searches around it and shows three findings you can ship next. Free check: https://porteur.ai/