How to Optimize Documentation Pages for SEO, GEO, and Agent Discovery

To optimize a documentation page for SEO, GEO, and agent discovery, give it one dominant question and one stable, descriptive URL. Repeat the same task or decision in the title, description, H1, opening 200 words, and section headings. Then check that the body actually delivers the promised result. This lesson focuses on being found. It does not try to teach every part of writing an executable guide. The later course material will cover complete procedures, runnable examples, failure recovery, page archetypes, and full worked transformations.

Optimize seven documentation discovery fields

By the end of the lesson, you will have:

one sentence stating the question the page owns;
one stable folder and slug path written in audience language;
a task-shaped title and matching H1;
a useful search description;
an answer-first opening of no more than a few short paragraphs;
headings that still make sense when retrieved alone;
a short editorial record showing what was verified;
a 30-minute process you can repeat across an existing documentation site.

Use one real page while you work through the lesson. Do not wait until the end to apply the steps.

Keep documentation findability and usability aligned

A documentation page has two audience jobs:

A person or agent must be able to find and select the page.
After selecting it, the person or agent must be able to use the answer successfully.

This lesson works on the first job. The two jobs are connected: a page should not earn a click for a task it cannot complete. Every title and description therefore needs a promise test:

If someone selects this result, does the page actually deliver the outcome it names?

If the answer is no, rewrite the body or narrow the promise. Do not use stronger metadata to disguise a weaker page.

Step 1: audit the documentation page contract

A useful documentation page has one address and nine content parts:

Priority	Page part	Its job
Foundation	Owning URL	Gives the page one stable, descriptive location in the documentation hierarchy
1	Title	Names the task, decision, or exact error in user language
2	Description	Explains specifically what the page enables and distinguishes it from neighboring pages
3	H1	Confirms the question, product, and page identity after selection
4	Answer-first opening	Gives the direct answer, scope, product term, and expected result
5	Prerequisites	Lists every condition needed to begin
6	Complete answer	Supplies the runnable procedure, decision framework, or exact reference
7	Verification	Shows the expected result and how to check it
8	Limits and recovery	Explains conditions, errors, unsafe assumptions, and alternatives
9	One primary next step	Moves the reader to the next natural job

The owning URL and items 1–4 form the highest-priority editorial discovery surface. They are what a search result, answer engine, browser tab, citation, or retrieved chunk can use when deciding what the page is about. Items 5–9 keep the promise after selection. They still matter: a discoverable page that cannot be used is not successful. They are simply outside this focused lesson.

Audit the current documentation discovery fields

Open the page you are improving and copy these six fields into a blank note:

Current URL:
Current title:
Current description:
Current H1:
Current first 200 words:
Current H2 headings:

Read only that note. If the page’s job is unclear, continue with the steps below.

Step 2: give the page one dominant question

A page may answer related subquestions, but it should have one dominant reason to exist. Complete this sentence:

This page helps <audience> <complete task / make decision / fix error> with <product and qualifier>.

Example:

This page helps a developer create an Intercom contact with the REST API.

That is a usable page job. “This page documents the Intercom API” is too broad to guide a title, opening, or set of headings for one operation. Create a separate page when any of these changes materially:

the desired outcome;
the audience or prerequisite knowledge;
the product, framework, language, API version, or region;
the correct procedure;
the error diagnosis or recovery path;
the choice the reader must make.

Do not split a page just to manufacture more URLs. If two pages would repeat the same answer with only minor nouns changed, use one owner page with a clearly labeled variant.

Turn a broad documentation topic into one owner question

Broad page identity	Dominant question	Focused page identity
`Intercom API (2.16)`	How do I create a lead or user with the REST API?	`Create an Intercom Contact with the REST API`
`HTTP - Developers`	How do I upload a file through the Dropbox API?	`Upload a File with the Dropbox API`
`Displaying Availability`	How do I display a user’s open and busy Calendly time?	`Display User Availability with Calendly's API`

The broader reference or hub can remain. The focused page owns the searchable task and links back to the complete contract.

Step 3: choose a descriptive slug and folder structure

The full URL should explain where the answer belongs and what the page owns. Build the path from stable context to the specific job:

docs.example.com/<content area>/<topic or product>/<task, decision, error, or reference item>

Google recommends logical, human-readable URLs that use audience language, readable words instead of IDs, hyphens between words, consistent casing, and as few unnecessary parameters as possible. Apply that guidance with these rules:

use lowercase words separated by hyphens;
let every folder add stable context that helps identify the answer;
write the leaf slug around the task, decision, exact error, or reference item;
keep navigation order in the sidebar configuration, not in prefixes such as 01- or chapter-3-;
do not repeat a word when a parent folder already supplies the context;
add version, language, framework, or region folders only when they change the answer;
avoid dates, campaign names, team names, IDs, and UI labels that are likely to change;
use query parameters only for real variants, then control duplication and canonical signals;
add a permanent redirect whenever a published URL changes.

The leaf does not need to repeat the whole title. Judge the complete path, not the filename alone.

Bun uses folders to make a short leaf slug meaningful

Bun’s simple HTTP server guide uses:

/docs/guides/http/simple
      │      │     └─ specific variant
      │      └─────── topic
      └────────────── page type

The leaf simple would be meaningless at the root. Inside /guides/http/, the full path identifies a simple HTTP guide, while the title Write a simple HTTP server supplies the complete task. Use this pattern when parent folders are stable, audience-facing concepts—not internal team boundaries.

Stripe keeps the stable payment task in the path

Stripe’s payment guide uses:

/payments/accept-a-payment
     │             └─ user task
     └─────────────── product area

The task remains stable while the page offers variants for Checkout, Elements, iOS, Android, and React Native. The machine-readable page exposes those variants through parameters such as payment-ui and platform. The reusable lesson is to keep the enduring question in the path and treat interface choices as variants when they do not deserve separate owner pages. Because parameters can create duplicate crawl paths, verify canonicals and inventory rules rather than copying the implementation blindly.

MDN uses a deep taxonomy for exact reference retrieval

MDN’s HTTP 404 reference uses:

/en-US/docs/Web/HTTP/Reference/Status/404
   │        │    │       │        └─ exact reference item
   │        │    │       └────────── reference type
   │        │    └────────────────── protocol
   │        └─────────────────────── platform corpus
   └──────────────────────────────── locale

This path is deep, but each segment narrows the answer. Reference documentation often benefits from a predictable taxonomy because a developer or agent can infer neighboring contracts. Depth is not the problem; folders that add no audience-facing meaning are.

Cloudflare separates educational questions from product reference

Cloudflare’s DNS explainer uses:

/learning/dns/what-is-dns/
    │       │        └─ question
    │       └────────── topic
    └────────────────── content purpose

The /learning/ folder tells the reader to expect category education rather than configuration or API reference. The /dns/ folder groups related questions, and the leaf matches the beginner’s question. Use a purpose folder when it communicates a real audience intent; do not create one merely because the content team has that name.

Rewrite numbered course URLs around the page job

This course previously stored lesson order in the URL. The navigation configuration already owns that job, so the numbers added no retrieval value:

Before	After	Why the new path is clearer
`/theory/documentation-site/01-why-documentation-matters`	`/theory/documentation-site/why-documentation-matters`	Removes order metadata while preserving the exact question
`/theory/documentation-site/03-write-for-discovery`	`/theory/documentation-site/optimize-documentation-pages-for-seo-geo`	Names the object, action, and search disciplines
`/theory/documentation-site/04-research-documentation-questions`	`/theory/documentation-site/research-documentation-questions`	Keeps the research task and removes the chapter number
`/theory/documentation-site/05-build-technical-foundation`	`/theory/documentation-site/technical-foundation`	Uses the parent folder to supply the documentation-site context

The old paths should permanently redirect to the new owner pages. Renaming without redirects trades a cleaner slug for broken links and split identity.

Audit the proposed documentation URL

Read the full path without the title or sidebar:

Proposed canonical URL:
Audience words used in the path:
Meaning supplied by each folder:
Question or reference item supplied by the leaf:
Variant dimensions excluded from the canonical path:
Old URLs that need permanent redirects:

If the path cannot identify a useful content area and page job, rewrite it before publishing.

Step 4: write the title before the body

The title is a content decision, not final polish. It forces you to state which question the page owns. Use one of these patterns:

<Verb/task> + <product> + <important qualifier>
<Exact error code/message> + <product> + <fix intent>
<Choice A> vs <Choice B> + <decision context>
<Product> + <integration> + <outcome>

Silently add “How to” in front of a task title. If the result reads like a real question, the title is probably moving in the right direction:

Visible title: Upload a File with the Dropbox API
Mental test: How to upload a file with the Dropbox API

The visible title does not need to include “How to.” The test is a writing tool, not a template every page must display.

Rewrite generic documentation titles around the task

Before	Why it is weak	After	What changed
`Create form`	Product and interface are ambiguous	`Create a Form Programmatically with the Typeform API`	Adds product, interface, and method
`Displaying the Availability of Your Users`	Omits Calendly, API, and output	`Display User Availability in a Table or Calendar with Calendly's API`	Names product, interface, and real outputs
`List records`	Hides filtering and pagination jobs	`List, Filter, and Paginate Records with Airtable's Web API`	Adds tasks the page already answers
`HTTP - Developers - Dropbox`	Names a protocol hub, not the task	`Upload a File with the Dropbox API`	Gives the operation its own identity
`Intercom API (2.16)`	Whole-API H1 conflicts with the operation route	`Create an Intercom Contact with the REST API`	Aligns the page with one operation

Avoid titles such as Overview, Getting Started, Method 3, Authentication, Forms, and More Information. They can work as sidebar labels, but they do not express a complete question in a search result, citation, browser history, or retrieved chunk. The new title is approved only when the body delivers the promise. A credential page does not become a complete integration guide merely because its title says “Send a message.”

Combine audience language with exact product terminology

Lead with the language someone knows before learning the product term, then introduce the exact term needed to use the product. Instead of choosing between “get rows from a table” and Airtable’s List records, write:

Retrieve and paginate rows from an Airtable table with the List records operation.

This lets the page match the task while teaching the product vocabulary.

Test three candidate documentation titles

Write three possible titles for your page. Reject any title that:

could describe several pages on the same site;
promises an outcome the body does not complete;
depends on the sidebar for product context;
leads with an internal label an unfamiliar reader would not use.

Keep the clearest remaining title. Do not optimize for cleverness.

Step 5: write a useful description

The description should help someone decide whether this is the right page. Write it by hand after the title. A useful description:

states what the reader will accomplish;
uses concrete product, action, and qualifier nouns;
distinguishes the page from neighboring pages;
often fits in roughly 140–160 characters without treating length as a ranking rule;
avoids marketing adjectives and generic invitations;
describes content that already exists on the page.

Weak:

Airtable is a low-code platform for building collaborative apps.

Useful:

Retrieve records from an Airtable table, filter and sort the result, select fields, and follow offset pagination beyond the first 100 rows.

The weak description describes the company. The useful one describes the job, supported variations, and important pagination boundary.

Rewrite descriptions around the page outcome

Before	After	Why it works
Typeform `Create form`: no description	`Create a Typeform form from JSON, add fields and settings, and understand the request schema and image requirements.`	Names input, output, and constraint
Airtable’s company description	`List records from an Airtable table with pagination, filtering, sorting, and selected fields.`	Distinguishes this operation from neighboring references
Dropbox’s consumer marketing description	`Upload files up to 150 MiB with Dropbox API v2, including the required scope, headers, binary body, and large-file path.`	Represents the developer task and size-dependent decision
Intercom `Create contact`: no description	`Create an Intercom lead or user with POST /contacts, including authentication, version header, identifiers, and response fields.`	Names endpoint, object types, and contract detail

Do not automatically copy the first paragraph into the description. The opening and description have different jobs and should not repeat the same sentence.

Step 6: make the first 200 words route the reader

The opening should answer four questions quickly:

What should the reader do or choose?
When does this answer apply?
What product term, interface, or version do they need to know?
What result will show success?

Use this pattern:

To <complete task>, use <exact product mechanism> to <how it works>.
This applies to <scope or important qualifier>.
The task is complete when <observable result>.

Before: an opening that describes the company instead of the task

Airtable is a low-code platform for building collaborative apps. Our powerful platform helps teams organize their most important work.

This could introduce almost any Airtable page. It does not route a developer to the List records operation.

After: an opening that routes to the Airtable operation

# List, filter, and paginate Airtable records

Send `GET /v0/{baseId}/{tableIdOrName}` to retrieve records from an Airtable table. The API returns up
to 100 records per page; when a response includes an `offset`, pass it in the next request to continue.
Use query parameters to filter, sort, format, or limit the returned fields.

The rewritten opening names the operation, product object, page-size boundary, continuation mechanism, and supported variations. A reader or retrieved chunk can recognize the answer before reading the rest of the page. Avoid company history, slogans, broad category education, and navigation instructions before the answer. Link to a concept page if background is helpful but not required.

Step 7: use headings as retrieval keys

A search engine or agent may surface one section without the page title. Make each H2 understandable on its own. Weak headings:

Setup
Usage
Example
Errors
Option 2

Useful headings:

Create a Typeform personal access token
Combine Calendly schedules and busy times
Page through more than 100 Airtable records
Upload files larger than 150 MiB with a Dropbox session
Send the Intercom-Version header

Rewrite generic documentation headings as retrieval keys

Before	After	Retrieval improvement
`Before you begin`	`Create a Typeform token with form-write access`	Names the prerequisite and purpose
`Using a table`	`Render Calendly availability and busy times in a table`	Keeps both inputs visible
`Query parameters`	`Filter and sort Airtable records with query parameters`	Makes the supported actions explicit
`Content-upload endpoints`	`Send file bytes as application/octet-stream`	Exposes the nonstandard body requirement
`Request`	`Create an Intercom contact with POST /contacts`	Preserves object, action, and endpoint
`Errors`	`Decide whether an upload conflict is safe to retry`	Turns a generic bucket into a recovery decision

Use a logical hierarchy and do not skip heading levels for visual styling. Keep response tabs, status codes, and component labels out of the article H1 outline.

Test the H1 and H2 map without the body copy

Copy only the H1 and H2 headings into a note. A reviewer should be able to tell:

what the page helps them do;
the major steps or decisions;
which product or interface applies;
where limits and recovery appear.

If the outline reads like Overview → Setup → Usage → Example → Errors, rewrite it before polishing the body.

Step 8: use a discovery-first editorial workflow

The workflow prevents a strong-looking title from drifting away from product truth.

Write a one-page documentation discovery brief

Primary question:
Also asked as:
Audience and stage:
Product, version, region, and locale:
Source evidence:
Owning URL:
Current title, description, H1, opening, and H2s:
Proposed title:
Required answer and success result:
Unknown facts or claims:
Product owner and reviewer:

If the user language or question priority is unknown, mark it instead of inventing evidence:

RESEARCH PLACEHOLDER: confirm wording and priority through the Question Map.

You will complete that work in Research Documentation Questions.

Draft the URL and five editorial discovery fields together

Write the URL, title, description, H1, first 200 words, and H2 outline in one pass. Read them without the sidebar or surrounding site.

Run the documentation promise test

Hide the proposed title and give the remaining page to a reviewer:

Can this page deliver the task named by the proposed title?

If it only supplies a prerequisite or sends the reader elsewhere, narrow the title or plan a body rewrite.

Verify the product facts behind the page promise

The product or subject-matter owner checks terminology, version, endpoint, permissions, limits, regions, results, errors, and current-versus-deprecated behavior. Mark unresolved facts with VERIFY; do not smooth uncertainty into authoritative copy.

Test every documentation representation in isolation

Review only:

the title;
the canonical URL;
the description;
the first 200 words;
the H1 and H2 list;
the llms.txt link description, when present;
the generated Markdown.

Each representation should identify the same page job. A whole-API HTML page and an operation-level Markdown page do not have one coherent identity.

Publish the documentation page with an owner and review date

Record the responsible product owner, independent reviewer, and last-reviewed date for pages that are high-risk or change quickly. Update dateModified only after material review, not on every build.

Step 9: run a 30-minute documentation improvement pass

Use this pass when a full rewrite is not yet possible.

Minutes 0–5: name the documentation question and owner URL

Write the one-sentence dominant question.
Confirm the current URL should own it.
If the URL changes, record the permanent redirect before publishing.
Mark missing question evidence as RESEARCH PLACEHOLDER.

Minutes 5–10: fix the documentation search result

Rewrite the title around the real task.
Hand-write a description that distinguishes this page.
Confirm neither field overpromises the body.

Minutes 10–15: fix the first 200 words

Put the direct answer first.
Name the product mechanism, scope, and expected result.
Remove slogans, history, and navigation instructions before the answer.

Minutes 15–20: fix the documentation heading map

Rewrite vague H2s as tasks, questions, decisions, or symptoms.
Run the heading-only test.
Keep one article H1.

Minutes 20–25: verify the page promise and product facts

Check product terms, versions, limits, and claims.
Add VERIFY to unresolved facts.
Confirm the body delivers the title’s outcome.

Minutes 25–30: inspect HTML, Markdown, metadata, and machine indexes

Preview the search title and description.
Read the initial HTML and generated Markdown.
Check the llms.txt description when present.
Confirm the title, H1, opening, and headings describe one job.

Do not use the 30-minute pass to pretend a thin page is complete. Record body, technical, and research work as follow-up tasks.

Audit one documentation page after optimization

Complete this review sheet for one page:

Dominant question:
Old URL:
New canonical URL:
Permanent redirect:
Old title:
New title:
New description:
New H1:
New opening:
New H2 outline:
Promise test: pass / fail
Product verification: pass / VERIFY items
HTML and Markdown identity: pass / fail
Research follow-up:
Body follow-up:
Technical follow-up:

Worked Airtable documentation discovery audit

This example uses the public Airtable List records material reviewed on 8 August 2026. Recheck the live contract before using it as current product guidance.

Dominant question: How do I list, filter, and paginate records from an Airtable table?
Old URL: VERIFY current operation URL
New canonical URL: VERIFY a stable path that identifies Airtable records and the list operation
Permanent redirect: required only if the published path changes
Old title: List records
New title: List, Filter, and Paginate Records with Airtable's Web API
New description: List records from an Airtable table with pagination, filtering, sorting, and selected fields.
New H1: List, filter, and paginate Airtable records
New opening: Send GET /v0/{baseId}/{tableIdOrName} to retrieve records. When the response includes an offset, pass it in the next request to continue.
New H2 outline:
  - Authenticate an Airtable List records request
  - Request the first page of records
  - Filter and sort records with query parameters
  - Request the next page with the offset
  - Fix token, table, and offset errors
Promise test: pass only when the body shows the first and next requests
Product verification: VERIFY current page-size, endpoint, offset, and token-scope facts
HTML and Markdown identity: verify both routes use the same operation-level title and answer
Research follow-up: confirm the question wording and priority with search and customer evidence
Body follow-up: add captured first-page and next-page responses
Technical follow-up: make the initial HTML identify the operation without crawler-specific rendering

The lesson is complete when another person can read only those fields, identify the page’s exact job, and confirm that the existing body keeps the promise. Next, learn how to replace research placeholders with evidence in Research Documentation Questions. For crawler, canonical, Markdown, and machine-file delivery, continue to the Technical Foundation.

​Optimize seven documentation discovery fields

​Keep documentation findability and usability aligned

​Step 1: audit the documentation page contract

​Audit the current documentation discovery fields

​Step 2: give the page one dominant question

​Turn a broad documentation topic into one owner question

​Step 3: choose a descriptive slug and folder structure

​Bun uses folders to make a short leaf slug meaningful

​Stripe keeps the stable payment task in the path

​MDN uses a deep taxonomy for exact reference retrieval

​Cloudflare separates educational questions from product reference

​Rewrite numbered course URLs around the page job

​Audit the proposed documentation URL

​Step 4: write the title before the body

​Rewrite generic documentation titles around the task

​Combine audience language with exact product terminology

​Test three candidate documentation titles

​Step 5: write a useful description

​Rewrite descriptions around the page outcome

​Step 6: make the first 200 words route the reader

​Before: an opening that describes the company instead of the task

​After: an opening that routes to the Airtable operation

​Step 7: use headings as retrieval keys

​Rewrite generic documentation headings as retrieval keys

​Test the H1 and H2 map without the body copy

​Step 8: use a discovery-first editorial workflow

​Write a one-page documentation discovery brief

​Draft the URL and five editorial discovery fields together

​Run the documentation promise test

​Verify the product facts behind the page promise

​Test every documentation representation in isolation

​Publish the documentation page with an owner and review date

​Step 9: run a 30-minute documentation improvement pass

​Minutes 0–5: name the documentation question and owner URL

​Minutes 5–10: fix the documentation search result

​Minutes 10–15: fix the first 200 words

​Minutes 15–20: fix the documentation heading map

​Minutes 20–25: verify the page promise and product facts

​Minutes 25–30: inspect HTML, Markdown, metadata, and machine indexes

​Audit one documentation page after optimization

​Worked Airtable documentation discovery audit