{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-learn/ai-for-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Learn","type":"markdown"},"seo":{"title":"Use AI to help developers find and understand your APIs faster","description":"Structure docs for task-shaped questions, use Revel for external developers and Reef for internal discovery, and expose llms.txt-style signals assistants can read.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"use-ai-to-help-developers-find-and-understand-your-apis-faster","__idx":0},"children":["Use AI to help developers find and understand your APIs faster"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Developers increasingly ask how do I authenticate instead of reading every guide in order. You can design for that shift by publishing clear external docs in Revel, maintaining an internal catalog in Reef, and shaping pages so search and assistants retrieve the right fragment on the first try. Task-based testing in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-usability-testing"},"children":["Use AI to test your documentation's usability"]}," complements this work by showing where linear docs still fail."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"from-linear-reading-to-task-shaped-questions","__idx":1},"children":["From linear reading to task-shaped questions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Traditional portals assume a patient reader who follows your table of contents. Integrators often arrive with a deadline and a single blocker. When assistants summarize docs, they reward pages that state prerequisites, show a minimal working request, and link errors to fixes. Write sections around tasks (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Get an access token"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["List webhooks"]},") rather than around internal team names."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The shift affects how you measure success. Page views can rise while time-to-first-successful-call stays flat. Track whether a reader completes a task without opening more than two pages. Usability testing with AI, described in the linked usability article, is one way to see where navigation still hides the answer."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"external-developers-and-revel","__idx":2},"children":["External developers and Revel"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/revel"},"children":["Revel"]}," is the external developer portal surface where partners and customers onboard. Put authentication, rate limits, and quickstarts where search and navigation can reach them in one or two clicks. Configure hosted search and assistant features using ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/config/search"},"children":["Search configuration"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/config/ai-assistant"},"children":["AI assistant configuration"]}," when your project uses those Realm options."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["External readers care about stability promises and copy-paste examples. Keep changelog links adjacent to breaking changes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For partner-only APIs, state entitlement requirements in the first paragraph so search does not surface steps the reader cannot run. Internal Reef entries can carry richer operational detail without exposing it on Revel."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"internal-teams-and-reef","__idx":3},"children":["Internal teams and Reef"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Employees need a different view: ownership, scorecards, and which API is canonical when duplicates exist. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/reef"},"children":["Reef"]}," supports internal catalog and discovery so engineers do not file duplicate services. Pair Reef metadata with the same task headings you use externally so internal search returns familiar language."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"doc-structure-models-can-navigate","__idx":4},"children":["Doc structure models can navigate"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Assistants retrieve smaller chunks when headings are specific and when each page answers one primary task. Put authentication before reference detail. Keep error codes on the same page as the operation they belong to. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/blog/optimizations-to-make-to-your-docs-for-llms"},"children":["optimizations for LLMs"]}," article lists practical edits that also help human skimmers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"page-template-you-can-reuse","__idx":5},"children":["Page template you can reuse"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"# Task title (verb + object)\n\nPrerequisites: links to auth and environment setup.\n\n## Steps\nNumbered calls with request and response samples.\n\n## Errors\nTable mapping codes to causes and fixes.\n\n## Related\nLinks to adjacent tasks only.\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"llmstxt-and-assistant-ready-surfaces","__idx":6},"children":["llms.txt and assistant-ready surfaces"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Publish a machine-readable index such as ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/llms.txt"},"children":["llms.txt"]}," on your own site when you want tools to discover high-value entry points without crawling the entire portal. This does not replace good page structure, but it signals which guides matter most. MCP and similar integrations work best when underlying pages already separate tasks cleanly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List only stable entry points in that index: authentication, quickstarts, changelog, and status. Rotate the list when you deprecate flows. Pair it with the lifecycle framing in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-modern-api-docs"},"children":["How AI fits into modern API documentation"]}," so writers remember that assistants consume the same pages humans read."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"retrieval-friendly-snippets","__idx":7},"children":["Retrieval-friendly snippets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep code samples copy-paste ready with real hostnames for sandbox, not placeholders like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api.example.com"]}," unless your product truly uses them. Put scopes and headers in the first sample block. Models quote the first example more often than the third."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph TD\n Q[Developer question] --> R{Audience}\n R -->|External| V[Revel docs search]\n R -->|Internal| F[Reef catalog]\n V --> A[Answer fragment]\n F --> A\n A --> N[Next task link]\n","diagramHtml":"

External

Internal

Developer question

Audience

Revel docs search

Reef catalog

Answer fragment

Next task link

","diagramHtmlDark":"

External

Internal

Developer question

Audience

Revel docs search

Reef catalog

Answer fragment

Next task link

"},"children":["graph TD\n Q[Developer question] --> R{Audience}\n R -->|External| V[Revel docs search]\n R -->|Internal| F[Reef catalog]\n V --> A[Answer fragment]\n F --> A\n A --> N[Next task link]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The diagram is simple on purpose: every answer should point to the next step."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":8},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Test five onboarding tasks monthly with only public docs, as described in the usability article."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mirror task titles between internal and external docs when the workflow is the same."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Surface auth and environment setup on every quickstart, not only on a distant overview."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Measure time-to-first-successful-call, not page views alone."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Record which pages assistants cite when answers are wrong, then fix headings on those pages first."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep internal Reef entries linked from external Revel pages when partners should not see internal routes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Review search queries quarterly and add missing task pages when the same question repeats."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Publish a short getting-started path that links three tasks in order so both humans and assistants follow the same sequence."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-assistants-cannot-infer","__idx":9},"children":["What assistants cannot infer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Models guess when specs omit error shapes or when examples omit auth headers. They may combine outdated blog posts with current reference if you do not deprecate clearly. Assistants do not replace partner agreements or regulatory wording that legal must approve."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you expose MCP tools to agents, document the same auth and rate limits on the human-facing page. Agents should not learn a shortcut that your public policy forbids. Internal Reef scorecards help engineers see which APIs are production-ready before external Revel pages promise the same stability."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":10},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Serve external developers in Revel, internal discovery in Reef, and write both for task-shaped questions. Add search and assistant configuration deliberately, and keep pages small enough that the right fragment wins retrieval. Re-test onboarding tasks after every major navigation change."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-more","__idx":11},"children":["Learn more"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/revel"},"children":["Revel"]}," is the external developer portal where structured quickstarts, search, and assistant features help integrators finish tasks without reading the entire site."]}]},"headings":[{"value":"Use AI to help developers find and understand your APIs faster","id":"use-ai-to-help-developers-find-and-understand-your-apis-faster","depth":1},{"value":"From linear reading to task-shaped questions","id":"from-linear-reading-to-task-shaped-questions","depth":2},{"value":"External developers and Revel","id":"external-developers-and-revel","depth":2},{"value":"Internal teams and Reef","id":"internal-teams-and-reef","depth":2},{"value":"Doc structure models can navigate","id":"doc-structure-models-can-navigate","depth":2},{"value":"Page template you can reuse","id":"page-template-you-can-reuse","depth":3},{"value":"llms.txt and assistant-ready surfaces","id":"llmstxt-and-assistant-ready-surfaces","depth":2},{"value":"Retrieval-friendly snippets","id":"retrieval-friendly-snippets","depth":3},{"value":"Best practices","id":"best-practices","depth":2},{"value":"What assistants cannot infer","id":"what-assistants-cannot-infer","depth":2},{"value":"Summary","id":"summary","depth":2},{"value":"Learn more","id":"learn-more","depth":2}],"frontmatter":{"seo":{"title":"Use AI to help developers find and understand your APIs faster","description":"Structure docs for task-shaped questions, use Revel for external developers and Reef for internal discovery, and expose llms.txt-style signals assistants can read."}},"lastModified":"2026-05-22T12:10:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/learn/ai-for-docs/ai-help-developers-find-understand-apis","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}