diff --git a/learn/ai-for-docs/ai-optimize-api-docs-llms-ai-search.md b/learn/ai-for-docs/ai-optimize-api-docs-llms-ai-search.md new file mode 100644 index 000000000..d09d63558 --- /dev/null +++ b/learn/ai-for-docs/ai-optimize-api-docs-llms-ai-search.md @@ -0,0 +1,59 @@ +--- +seo: + title: Use AI to optimize your API docs for LLMs and AI search + description: How to structure headings, terminology, and code examples so LLMs and AI search tools retrieve accurate answers from your API docs. +--- + +# Use AI to optimize your API docs for LLMs and AI search + +Developers increasingly ask an AI assistant how to authenticate instead of reading a reference page in order. When the underlying docs are not ready for that kind of reading, the assistant returns a mix of old and new terms, a broken code snippet, or an answer pulled from the wrong section entirely. The developer opens a support ticket, and the team never learns that the docs, not the assistant, caused the confusion. + +This is already showing up in the numbers. A recent Stack Overflow Developer Survey found that 84% of developers now use, or plan to use, AI tools in their workflow, while 46% say they do not trust the accuracy of what those tools return, up from 31% a year earlier, according to [Redocly's analysis of how to optimize your docs for LLMs](https://redocly.com/blog/optimizations-to-make-to-your-docs-for-llms). This article walks through why that mistrust builds and what to change in your headings, terminology, formatting, and testing so both people and AI search tools get the right answer on the first try. + +## Why AI search changes what counts as good docs + +A human reader skims a page, notices the visual hierarchy, and fills in missing detail from context. An AI model does none of that. Most retrieval systems break a page into paragraph-sized chunks and store each one as a "vector embedding," a numeric representation used to find the passage that best matches a question. When a single section mixes two topics, such as authentication and rate limits, the model cannot tell them apart, so a question about one pulls in details about the other. + +The same mechanism causes wrong-section errors. If two pages describe similar-sounding operations, the embedding for one can sit close enough to the other that the assistant retrieves the wrong page and answers with confidence anyway. Fixing this is less about writing more content and more about organizing what already exists so each chunk answers one question well. + +## Structure your docs so AI can parse them + +### Keep heading hierarchy predictable + +AI systems use headings as a map of how concepts relate, so skipping levels (jumping from an `H1` straight to an `H3`) breaks that map and can cause the model to misread which section a detail belongs to. A predictable pattern, main topic as `H2`, subtopics as `H3`, lets an assistant find the authentication section and know that API key setup and token management both belong under it. Documentation platforms that generate structure from an OpenAPI description handle much of this automatically, which frees your team to check accuracy instead of fixing heading levels by hand. + +### Use one term for each concept + +Calling the same thing an "API key" in one paragraph and an "access token" in the next forces a model to guess whether you mean two different things or one. Pick a single term per concept and use it everywhere, even when the repetition reads a little stiff to a human. Linting rules, the kind Redocly CLI can enforce across an entire spec, catch this kind of drift automatically once you decide on the term. + +### Format code examples so they survive processing + +Inline commands mixed into a sentence often get merged or altered when an assistant reformats them into an answer. Put install commands and import statements in their own fenced code blocks instead of folding them into a sentence, and keep one action per block. That small change is often the fastest win available, because it fixes the exact spot where developers copy and paste directly from an AI's response. + +### Describe diagrams and screenshots in words + +An assistant working from text alone cannot see your authentication flow diagram, so anything the image communicates needs a text version nearby. A short numbered list of the same steps the diagram shows gives the model something to retrieve and quote, instead of leaving that information invisible to it. + +### Say exactly what you mean + +Pronouns such as "it" or "this" force an assistant to guess which noun they refer to, and it often guesses wrong. Naming the config file, the server, or the endpoint again, even when a human reader would find the repeat unnecessary, removes an entire category of retrieval error. + +## Watch for terminology drift over time + +Feature names change, branches get renamed, and old pages linger in a vector index long after the product moves on. When an API evolves from a "master branch" to a "main branch" but earlier docs never get updated, a developer asking about the current workflow can receive instructions built for the old one. Because inconsistencies compound the longer they sit, a periodic audit for outdated terms is worth scheduling rather than leaving until a support ticket flags it. + +## Design pages for people and assistants together + +None of this means writing two versions of your docs. [Task-shaped headings](https://redocly.com/learn/ai-for-docs/ai-help-developers-find-understand-apis) such as "get an access token" or "list webhooks" work well for a developer skimming a table of contents and for an assistant retrieving one fragment to answer one question, because both readers are looking for the same thing. External developers using Revel and internal teams using Reef can share the same task-based headings, so search inside either surface returns familiar language instead of two competing vocabularies. + +Publishing an [llms.txt](https://redocly.com/llms.txt) file gives AI tools a short, machine-readable index of your most important pages, such as authentication, quickstarts, and changelog, without asking them to crawl the entire site. Redocly [automates the creation of an llms.txt file](https://redocly.com/blog/updates-2025-05) from the same OpenAPI-driven build that generates the rest of your docs, so the index stays current as pages change instead of drifting out of sync. + +## Test how AI actually reads your docs + +The most reliable way to know whether these changes worked is to ask an AI tool the same questions a developer would: how do I authenticate, show me a request example for this endpoint, what does this error code mean. When the answer is accurate and complete, the structure behind it is doing its job. When the model mixes up terms or skips a step, that mismatch points to the exact page worth fixing next, a practice covered in more depth in [testing your documentation's usability](https://redocly.com/learn/ai-for-docs/ai-usability-testing) with AI directly. + +Because [OpenAPI-driven documentation](https://redocly.com/learn/ai-for-docs/ai-modern-api-docs) generates consistent headings and formatting by default, teams that build docs this way start the testing process with fewer problems to find. Track time to a developer's first successful call rather than page views alone, since a rising view count paired with a flat success rate usually means AI search is sending readers to a page that looks relevant but does not answer their question. + +## How Redocly can help + +Once your docs are structured for AI retrieval, the surface developers actually search still matters. [Revel](https://redocly.com/revel) is Redocly's external developer portal, and its hosted [search configuration](https://redocly.com/docs/realm/config/search) and [AI assistant configuration](https://redocly.com/docs/realm/config/ai-assistant) let you tune how both traditional search and conversational AI features retrieve answers from the same task-shaped pages this article describes. Instead of hoping a generic search bar finds the right fragment, Revel gives you direct control over the surface where people and AI search tools meet your docs. diff --git a/learn/ai-for-docs/sidebars.yaml b/learn/ai-for-docs/sidebars.yaml index 7dd3c8899..ab14ad4f9 100644 --- a/learn/ai-for-docs/sidebars.yaml +++ b/learn/ai-for-docs/sidebars.yaml @@ -30,6 +30,8 @@ label: Use AI to build a searchable API catalog for your team - page: ai-help-developers-find-understand-apis.md label: Use AI to help developers find and understand your APIs faster +- page: ai-optimize-api-docs-llms-ai-search.md + label: Use AI to optimize your API docs for LLMs and AI search - page: ai-check-terminology-consistency-across-docs.md label: Use AI to check terminology consistency across your docs - page: ai-usability-testing.md