> ## Documentation Index > Fetch the complete documentation index at: https://docs.synscribe.com/llms.txt > Use this file to discover all available pages before exploring further. # How to Optimize Documentation Pages for SEO, GEO, and Agent Discovery > Optimize a documentation page's question, URL, title, description, opening 200 words, and headings without promising more than the page delivers. 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: 1. A person or agent must be able to **find and select** the page. 2. 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: ```text theme={null} 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: ```text theme={null} This page helps with . ``` Example: ```text theme={null} 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: ```text theme={null} docs.example.com/// ``` [Google recommends](https://developers.google.com/search/docs/crawling-indexing/url-structure) 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](https://bun.com/docs/guides/http/simple) uses: ```text theme={null} /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](https://docs.stripe.com/payments/accept-a-payment) uses: ```text theme={null} /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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404) uses: ```text theme={null} /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](https://www.cloudflare.com/learning/dns/what-is-dns/) uses: ```text theme={null} /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: ```text theme={null} 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: ```text theme={null} + + + + vs + + + ``` 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: ```text theme={null} 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: 1. What should the reader do or choose? 2. When does this answer apply? 3. What product term, interface, or version do they need to know? 4. What result will show success? Use this pattern: ```text theme={null} To , use to . This applies to . The task is complete when . ``` ### 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 ```markdown theme={null} # 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 ```text theme={null} 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: ```text theme={null} RESEARCH PLACEHOLDER: confirm wording and priority through the Question Map. ``` You will complete that work in [Research Documentation Questions](/theory/documentation-site/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: ```text theme={null} 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. ```text theme={null} 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](/theory/documentation-site/research-documentation-questions). For crawler, canonical, Markdown, and machine-file delivery, continue to the [Technical Foundation](/theory/documentation-site/technical-foundation).