{"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 find gaps in your documentation coverage","description":"Use Redocly CLI lint for missing fields in specs and AI for missing workflows in prose, then use Respect monitoring for gaps that appear only at runtime.","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-find-gaps-in-your-documentation-coverage","__idx":0},"children":["Use AI to find gaps in your documentation coverage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Coverage is not a page count. A service can have a description on every path while still failing new integrators because the tutorial skips token refresh or assumes a sandbox that is never defined. You need two detectors: lint for holes in the OpenAPI contract, and AI for holes in multi-step stories, with Respect catching behavior your spec and prose both got wrong."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"two-kinds-of-gaps","__idx":1},"children":["Two kinds of gaps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Structural gaps live in the spec or reference tables: empty descriptions, parameters without examples, operations missing error responses, broken $ref targets. Workflow gaps live between pages: the guide says \"create a subscription\" but never links how to authenticate, or documents sandbox keys without saying where to create them."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Confusing the two leads to the wrong fix. Adding lint rules will not teach a tutorial to mention prerequisites. Asking AI to \"review coverage\" without a checklist produces vague essays. Split the work deliberately."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph TD\n O[OpenAPI plus docs set] --> L[Redocly CLI lint]\n O --> A[AI workflow review]\n O --> R[Respect live workflows]\n L --> S[Structural gap list]\n A --> W[Workflow gap list]\n R --> M[Runtime mismatch alerts]\n","diagramHtml":"

OpenAPI plus docs set

Redocly CLI lint

AI workflow review

Respect live workflows

Structural gap list

Workflow gap list

Runtime mismatch alerts

","diagramHtmlDark":"

OpenAPI plus docs set

Redocly CLI lint

AI workflow review

Respect live workflows

Structural gap list

Workflow gap list

Runtime mismatch alerts

"},"children":["graph TD\n O[OpenAPI plus docs set] --> L[Redocly CLI lint]\n O --> A[AI workflow review]\n O --> R[Respect live workflows]\n L --> S[Structural gap list]\n A --> W[Workflow gap list]\n R --> M[Runtime mismatch alerts]\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"find-structural-gaps-with-redocly-cli","__idx":2},"children":["Find structural gaps with Redocly CLI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/built-in-rules"},"children":["Built-in rules"]}," such as security-defined and operation-operationId-unique catch classes of missing metadata your organization already agreed to require. Start from the recommended ruleset, then tighten severity when teams are ready."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When your standard goes further, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/configurable-rules"},"children":["configurable rules"]}," express org-specific coverage: require examples on path parameters, forbid empty tag descriptions, or enforce a minimum response set per operation. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/guides/configure-rules"},"children":["guide to configuring a ruleset"]}," shows how to extend recommended with a shared org-api-standards.yaml file every repository imports."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/commands/lint"},"children":["lint command"]}," in CI on every OpenAPI path. Failures should map to owners the same way test failures do. A green lint run means the contract metadata you encoded is present, not that prose tutorials are complete."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"coverage-checklist-for-lint","__idx":3},"children":["Coverage checklist for lint"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"- [ ] Every operation has summary and description\n- [ ] Path and query parameters include description and example where required\n- [ ] 4xx responses documented for authenticated routes\n- [ ] security schemes defined and referenced on sensitive operations\n- [ ] Tags have descriptions when your standard requires them\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Promote recurring AI findings into new rule entries when they can be expressed as assertions, the same pattern as style guide enforcement."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"find-workflow-gaps-with-ai","__idx":4},"children":["Find workflow gaps with AI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-usability-testing"},"children":["Use AI as a usability tester"]}," frames the right question: can someone finish a real task with only public docs? Adapt that for coverage audits by naming workflows your analytics or support team already knows matter."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"You are auditing documentation coverage for integrators.\n\nInputs:\n- Table of contents or sitemap (headings and URLs only)\n- OpenAPI table of contents (tags and operation summaries)\n\nFor each workflow below, list:\n1. Steps documented with links\n2. Steps missing or only implied\n3. Assumed knowledge not defined elsewhere\n\nWorkflows:\n- New developer: account, API key, first authenticated request\n- Webhook consumer: subscribe, verify signature, retry policy\n- Rate limit handling: detect 429, backoff, resume\n\nDo not invent endpoints. Cite missing sections by heading or \"missing\".\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Workflow gaps often show up as assumed knowledge: terms used before definition, environment variables mentioned once, or error codes listed without remediation steps. Fix them by adding a subsection or a cross-link, not by lengthening unrelated reference pages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-and-after-pagination-tutorial","__idx":5},"children":["Before and after: pagination tutorial"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before: a tutorial jumps from \"list users\" to \"handle large datasets\" without stating default page size, cursor field names, or end-of-list behavior."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After: the same tutorial adds prerequisites linking to authentication, documents limit and cursor query parameters with examples, and points to the rate limit guide when responses include 429."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["AI helps you notice the jump; lint might still pass because each endpoint page is individually valid. Humans choose the narrative order."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"runtime-gaps-with-respect","__idx":6},"children":["Runtime gaps with Respect"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some gaps appear only when code ships: response fields differ from the schema, status codes change, or sandbox behavior diverges from production. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/respect"},"children":["Respect"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/respect/use-cases"},"children":["Respect use cases"]}," include running Arazzo workflows on a schedule against live endpoints and alerting when results diverge from the spec you publish."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treat Respect alerts as coverage signals for your docs team, not only for API owners. When a workflow fails because a field disappeared, update the spec and the guide section that showed the old shape. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/blog/api-contract-testing-arazzo"},"children":["API contract testing with Arazzo"]}," explains how multi-step flows fit CI and monitoring."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pair-coverage-review-with-editorial-standards","__idx":7},"children":["Pair coverage review with editorial standards"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-reviews"},"children":["Use AI to accelerate and improve reviews"]}," recommends short checklists instead of long style manuals for human and model reviewers. Reuse that pattern when you convert workflow gaps into writing standards: add a checklist line for prerequisites, cross-links, and runnable examples, then promote repeated failures into lint or into your CMS required fields."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When two teams own the same workflow, assign one operationId in OpenAPI as the anchor and link every tutorial step to that anchor so coverage discussions stay concrete in pull requests."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":8},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run lint on every spec change; run AI workflow audits on navigation or tutorial edits."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep a single backlog with labels structural, workflow, and runtime so writers know which tool owns the fix."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Link from inventory rows in your CMS to OpenAPI operationIds when possible so gaps stay traceable."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Re-run the same AI prompt after fixes; diff the missing lists to prove progress."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-each-layer-cannot-see","__idx":9},"children":["What each layer cannot see"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Lint does not read PDFs or video transcripts unless you model them in the spec. AI does not prove runtime correctness without evidence. Respect does not replace editorial judgment about what to document in the first place."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["None of the three replaces product managers who decide which workflows deserve first-class guides."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-balance","__idx":10},"children":["The balance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use lint to make contract metadata non-optional, AI to stress-test journeys across pages, and Respect to catch drift after release. Together they answer \"what is missing?\" with three different lenses instead of one vague score."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-more","__idx":11},"children":["Learn more"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To enforce required fields and examples in OpenAPI at scale, start with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Explore Redocly CLI"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/built-in-rules"},"children":["built-in rules"]},", then extend coverage with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/configurable-rules"},"children":["configurable rules"]},"."]}]},"headings":[{"value":"Use AI to find gaps in your documentation coverage","id":"use-ai-to-find-gaps-in-your-documentation-coverage","depth":1},{"value":"Two kinds of gaps","id":"two-kinds-of-gaps","depth":2},{"value":"Find structural gaps with Redocly CLI","id":"find-structural-gaps-with-redocly-cli","depth":2},{"value":"Coverage checklist for lint","id":"coverage-checklist-for-lint","depth":3},{"value":"Find workflow gaps with AI","id":"find-workflow-gaps-with-ai","depth":2},{"value":"Before and after: pagination tutorial","id":"before-and-after-pagination-tutorial","depth":2},{"value":"Runtime gaps with Respect","id":"runtime-gaps-with-respect","depth":2},{"value":"Pair coverage review with editorial standards","id":"pair-coverage-review-with-editorial-standards","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"What each layer cannot see","id":"what-each-layer-cannot-see","depth":2},{"value":"The balance","id":"the-balance","depth":2},{"value":"Learn more","id":"learn-more","depth":2}],"frontmatter":{"seo":{"title":"Use AI to find gaps in your documentation coverage","description":"Use Redocly CLI lint for missing fields in specs and AI for missing workflows in prose, then use Respect monitoring for gaps that appear only at runtime."}},"lastModified":"2026-05-22T12:10:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/learn/ai-for-docs/ai-find-gaps-documentation-coverage","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}