From 26b792db309a7a155fa66de13f8884888a9e03db Mon Sep 17 00:00:00 2001 From: Justin Dunham Date: Wed, 20 May 2026 23:18:50 -0700 Subject: [PATCH 1/3] Add AI for Docs learning articles Consolidate the AI-for-docs article set onto the current upstream main so it can be reviewed as one cohesive change. --- ...api-design-backward-compatibility-risks.md | 103 ++++++++++++ .../ai-auth-authorization-patterns.md | 146 ++++++++++++++++++ ...omate-documentation-reviews-pr-workflow.md | 101 ++++++++++++ .../ai-build-searchable-api-catalog.md | 134 ++++++++++++++++ ...eck-terminology-consistency-across-docs.md | 118 ++++++++++++++ .../ai-detect-drift-docs-live-api.md | 119 ++++++++++++++ .../ai-enforce-api-style-guide-at-scale.md | 142 +++++++++++++++++ ...orce-tone-style-consistency-across-docs.md | 86 +++++++++++ .../ai-find-duplicate-underused-apis.md | 103 ++++++++++++ .../ai-find-gaps-documentation-coverage.md | 115 ++++++++++++++ .../ai-generate-first-drafts-from-openapi.md | 101 ++++++++++++ ...ai-help-developers-find-understand-apis.md | 102 ++++++++++++ ...-review-api-design-gaps-inconsistencies.md | 126 +++++++++++++++ ...iew-code-examples-completeness-accuracy.md | 132 ++++++++++++++++ .../ai-review-docs-navigation-structure.md | 131 ++++++++++++++++ learn/ai-for-docs/ai-reviews.md | 8 +- learn/ai-for-docs/ai-usability-testing.md | 4 +- learn/ai-for-docs/sidebars.yaml | 35 ++++- pages/learning-center/cards.ts | 60 +++++++ 19 files changed, 1859 insertions(+), 7 deletions(-) create mode 100644 learn/ai-for-docs/ai-api-design-backward-compatibility-risks.md create mode 100644 learn/ai-for-docs/ai-auth-authorization-patterns.md create mode 100644 learn/ai-for-docs/ai-automate-documentation-reviews-pr-workflow.md create mode 100644 learn/ai-for-docs/ai-build-searchable-api-catalog.md create mode 100644 learn/ai-for-docs/ai-check-terminology-consistency-across-docs.md create mode 100644 learn/ai-for-docs/ai-detect-drift-docs-live-api.md create mode 100644 learn/ai-for-docs/ai-enforce-api-style-guide-at-scale.md create mode 100644 learn/ai-for-docs/ai-enforce-tone-style-consistency-across-docs.md create mode 100644 learn/ai-for-docs/ai-find-duplicate-underused-apis.md create mode 100644 learn/ai-for-docs/ai-find-gaps-documentation-coverage.md create mode 100644 learn/ai-for-docs/ai-generate-first-drafts-from-openapi.md create mode 100644 learn/ai-for-docs/ai-help-developers-find-understand-apis.md create mode 100644 learn/ai-for-docs/ai-review-api-design-gaps-inconsistencies.md create mode 100644 learn/ai-for-docs/ai-review-code-examples-completeness-accuracy.md create mode 100644 learn/ai-for-docs/ai-review-docs-navigation-structure.md diff --git a/learn/ai-for-docs/ai-api-design-backward-compatibility-risks.md b/learn/ai-for-docs/ai-api-design-backward-compatibility-risks.md new file mode 100644 index 00000000..27b6675d --- /dev/null +++ b/learn/ai-for-docs/ai-api-design-backward-compatibility-risks.md @@ -0,0 +1,103 @@ +--- +seo: + title: Use AI to review API design for backward compatibility risks + description: How to prompt an LLM to compare two OpenAPI versions for breaking changes, where human judgment ends, and how Redocly CLI plus Respect keep spec and live behavior aligned in CI. +--- + +# Use AI to review API design for backward compatibility risks + +Your public OpenAPI file is a promise to every client that already shipped. When a field disappears, a type tightens, or a path renames, the break often shows up first in someone else’s production log. A large language model can read two snapshots and narrate what changed. It is not a contract test. Pair that review with [API standards and governance](https://redocly.com/docs/cli/api-standards) in CI using [Explore Redocly CLI](https://redocly.com/docs/cli/), then let [Redocly Respect](https://redocly.com/docs/respect/) exercise critical workflows against a real server. + +This article covers what counts as breaking, how to prompt with two spec versions, and how CLI linting plus Respect’s Arazzo-aware runs complement AI judgment. + +## Why compatibility risk hides in large specs + +Breaking changes are not always obvious renames. Optional can become required, enums can lose values clients still send, or a response schema can drop a field your SDK exposed. Line-by-line YAML diffs fatigue humans fast. A model can hold both trees and highlight operations where caller behavior likely changed. + +The model may still hallucinate a reorder as a semantic change, or miss runtime behavior the spec never captured. Treat it as a reviewer that returns a prioritized list, and treat CI as the judge that fails the merge until the list is addressed or ruled out. + +## What counts as breaking for clients + +Agree with consumers what “breaking” means before you prompt: removed paths, renamed fields, stricter types, new required properties, changed status semantics, narrower enums. Additive changes still belong in a changelog but need not fail the gate. + +Have the model label each finding breaking, probably safe, or needs human decision. If some branches are additive-only, say that so new optional fields are not flagged as breaks. + +## How to prompt AI with two OpenAPI versions + +### Context block template + +Paste something shaped like this before the two files: + +```markdown {% process=false %} +You are comparing two OpenAPI 3.1 documents for backward compatibility. + +Roles: +- Document A: last published spec (tag v1.2.0). +- Document B: candidate release on branch release/1.3. + +Consumer contract (plain language): +- Mobile clients cache GET /users/{id} for 24 hours; removing any 200 response field they deserialize is breaking. +- Webhooks must accept unknown JSON keys on callbacks. + +Tasks: +1. List operations where request or response schemas narrowed for existing clients. +2. List renamed or removed paths, parameters, and schema properties with JSON pointers when possible. +3. Flag changes to error models that might alter client branching on status plus body shape. +4. Output a table: change, breaking Y/N/uncertain, suggested mitigation (deprecation header, versioned path, dual-write period). +``` + +Paste both files with clear delimiters. If policy lives only in Slack, summarize it in the prompt instead of assuming the model knows your release train. + +### Review checklist for the model + +Cover default responses, shared components reused across tags, and discriminator or oneOf shapes where a variant disappeared. Require operationIds on each row so tickets map to generators and tests. + +## Where Redocly CLI takes over + +AI output is not policy until it becomes rules and CI. [Explore Redocly CLI](https://redocly.com/docs/cli/) applies the same [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) and custom rules on every commit, so repeated enum removals fail the build instead of reappearing in chat. + +Use the [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) with `recommended` or `recommended-strict` as baseline, then encode your compatibility policy explicitly. The [lint command](https://redocly.com/docs/cli/commands/lint) also validates [What is Arazzo?](https://redocly.com/learn/arazzo/what-is-arazzo) files next to your OpenAPI roots. + +[Per-API configuration](https://redocly.com/docs/cli/configuration/apis) lets a public bundle stay stricter than an internal experimental service, similar to telling the model to ignore internal-only paths. + +## Where Respect takes over + +Specs can parse yet still misdescribe production. [Redocly Respect](https://redocly.com/docs/respect/) sends real requests and checks responses against OpenAPI and Arazzo expectations. [use cases for Respect](https://redocly.com/docs/respect/use-cases) include local runs, PR CI, and scheduled smoke tests against staging or production. + +Model the journeys that define compatibility: login then profile, create then poll, cancel then verify. When the server diverges from the description, Respect fails where a static diff would stay green. Use AI to summarize failure logs for humans, not to skip the run. + +## What AI cannot prove + +A model cannot prove every client tolerates a change. It does not execute your stack or know compensating behavior inside mobile apps. It should not be the only gate when SLAs attach to specific response shapes. + +Use AI to widen spec review, Respect to bind descriptions to deployed behavior, and humans for intentional breaks with explicit version bumps. + +## Best practices + +1. Always pass two concrete artifacts, for example bundled YAML from `main` and from your release branch, not a vague “what changed lately” question. +2. Ask for JSON pointers or operationIds so tickets map cleanly to engineering work. +3. Encode repeated AI findings as rules so the same mistake cannot return unnoticed. +4. Keep Arazzo workflows short and focused on compatibility-critical paths so CI stays fast and failures are interpretable. + +## What this approach cannot replace + +This approach cannot replace consumer-driven contract tests owned by client teams, canary analysis, or database migration review when behavior shifts outside HTTP. It is a structured spec review plus deterministic tooling, not a full release certification. + +## How the pieces fit together + +```mermaid +graph LR + A[OpenAPI A plus OpenAPI B] --> B[LLM compatibility review] + B --> C[Human updates spec and rules] + C --> D[Redocly CLI lint] + D --> E[Respect Arazzo runs] + E --> F[CI or scheduled gate] +``` + +AI widens the diff narrative. Redocly CLI enforces the spec text. Respect checks that the running API still honors the workflows your clients depend on. + +## Learn more + +Start with [Explore Redocly CLI](https://redocly.com/docs/cli/) for [API standards and governance](https://redocly.com/docs/cli/api-standards), [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules), and the [lint command](https://redocly.com/docs/cli/commands/lint) on every change. + +Add [Redocly Respect](https://redocly.com/docs/respect/) and [use cases for Respect](https://redocly.com/docs/respect/use-cases) when you need PR or scheduled runs that still fail if the live API drifts while the YAML stays valid. diff --git a/learn/ai-for-docs/ai-auth-authorization-patterns.md b/learn/ai-for-docs/ai-auth-authorization-patterns.md new file mode 100644 index 00000000..4af15fe7 --- /dev/null +++ b/learn/ai-for-docs/ai-auth-authorization-patterns.md @@ -0,0 +1,146 @@ +--- +seo: + title: Use AI to check authentication and authorization patterns + description: Spot missing scopes, inconsistent security schemes, and thin auth error docs in OpenAPI with a model, then enforce fixes with Redocly CLI lint before merge. +--- + +# Use AI to check authentication and authorization patterns + +You can ask a model to read your OpenAPI security model before handlers ship, then run the same file through Redocly CLI lint in the pull request. The learn article [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews) covers the wider review pattern; here the focus stays on schemes, scopes, route coverage, and the error contracts integrators need when credentials fail. + +## Why auth and authorization drift in API descriptions + +Teams add endpoints faster than they update `components.securitySchemes`. One route still documents API keys while the rest moved to OAuth2. Admin paths inherit a global bearer scheme but never list the scopes a caller needs. Documentation mentions 401 and 403 in prose while the spec only declares a generic 400. + +A model can compare many paths at once and ask whether each operation matches the story you tell about roles and trust boundaries. It does not replace threat modeling, but it gives you a patient reader for long YAML. + +## Inputs that keep the review grounded + +Paste a short auth model in plain language before the spec excerpt. Name actors (for example integrators, support staff, machine clients), which routes are public, and which actions require elevated roles. + +List invariants you already enforce in code, such as tenant isolation on every read, or that destructive verbs always require an admin scope. If the file is large, scope the excerpt to the surface you are changing and describe the rest in a sentence. + +### Auth context block you can paste + +```markdown {% process=false %} +Auth model: OAuth2 client credentials for integrators; session cookies for the dashboard. +Public: GET /status, GET /openapi.json +Roles: reader (read-only), admin (write + delete) + +Review securitySchemes, security requirements, and auth-related responses: +[paste OpenAPI excerpt] +``` + +## Prompt skeleton for auth and authorization + +Keep the ask structured so findings are easy to triage. + +```markdown {% process=false %} +You are reviewing authentication and authorization for [one sentence domain]. + +Please list: +1. Operations that should require credentials but have no security requirement. +2. Mismatches between security scheme names in operations and components.securitySchemes. +3. Missing or inconsistent OAuth scopes (or permissions) across related endpoints. +4. Operations that share a scheme but should differ by role or scope. +5. Missing or vague 401 and 403 responses, including whether examples match the scheme. +6. Public routes that should explicitly document security: [] if they are intentionally open. + +[paste OpenAPI or notes] +``` + +## Signals models often surface + +Across teams, reviews tend to cluster on a short set of themes. Orphan schemes appear when `components.securitySchemes` defines a name operations never reference. Scope gaps show up when write endpoints document fewer scopes than read endpoints on the same resource. Error gaps cluster when only 200 responses are declared, or when 401 and 403 reuse the same schema without explaining retry versus forbidden. Inheritance confusion happens when a global `security` block hides which routes are actually public. + +Treat the list as a prioritized backlog, not a verdict. Some routes are intentionally open, and some schemes are legacy until a migration finishes. + +## Thin before and after on security + +Before: + +```yaml {% process=false %} +paths: + /reports: + get: + summary: Download usage report + security: + - bearerAuth: [] +components: + securitySchemes: + BearerAuth: + type: http + scheme: bearer +``` + +After: + +```yaml {% process=false %} +paths: + /reports: + get: + summary: Download usage report + security: + - BearerAuth: [reports:read] + responses: + '401': + description: Missing or invalid bearer token + '403': + description: Caller lacks reports:read scope +components: + securitySchemes: + BearerAuth: + type: http + scheme: bearer + bearerFormat: JWT +``` + +The second sketch does not prove your threat model is complete, but it shows how a review nudges you toward aligned names, explicit scopes, and distinct failure responses before implementation hardens the wrong shape. + +```mermaid +graph LR + A[Auth model plus OpenAPI] --> B[Model review] + B --> C[Human edits] + C --> D[redocly lint] + D --> E[Pull request] +``` + +Run the loop while the document is still cheap to edit. + +## Where CLI lint takes over + +When you accept changes, run the [lint command](https://redocly.com/docs/cli/commands/lint) against the same file the model saw. Lint applies preprocessors and rules, reports problems in OpenAPI and related formats, and does not run decorators, which keeps this step focused on spec compliance rather than publishing transforms. + +The [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) catalog includes security-related checks. The [security-defined rule](https://redocly.com/docs/cli/rules/oas/security-defined) verifies that every operation or global security requirement is defined. If an API is intentionally public, the rule documentation shows declaring an empty requirement so readers know the omission is deliberate: + +```yaml {% process=false %} +security: [] +``` + +In continuous integration, point the same command at pull requests so every spec edit repeats local checks. Models sometimes suggest scheme names or extensions your ruleset has not whitelisted yet, and lint surfaces those mismatches early. + +If you have no local config yet, the command defaults to the [recommended ruleset](https://redocly.com/docs/cli/rules/recommended). As standards mature, add [configurable rules](https://redocly.com/docs/cli/rules/configurable-rules) for org-specific auth policies, such as requiring scope text in operation descriptions or forbidding duplicate scheme types on one path. The [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) walks through a practical baseline. + +Organizations that treat OpenAPI as law usually centralize how rules are authored and shared. The [API standards and governance](https://redocly.com/docs/cli/api-standards) page describes using the same configuration locally and in automation so developers see the same violations everywhere. + +## Best practices + +Ship the auth model as a short checklist, not a long policy essay, in the same message as the spec excerpt. + +Review one theme at a time on large files: scheme names first, then scopes, then error responses. + +Log model findings as tickets with path and operation anchors so humans can accept or reject with traceability. + +Combine model passes with deterministic tools so subjective completeness meets objective gates, which mirrors the guidance in [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews). + +## What this pairing cannot replace + +Models do not know your live identity provider configuration, token lifetimes, or penetration test results unless you state them. They can suggest scopes that sound reasonable but do not match what your authorization service enforces. Lint cannot judge whether a scope is too broad for a role; it checks that the document obeys the rules you configured. + +## Summary + +Use a structured prompt plus a plain-language auth model to surface scheme, scope, and error gaps early, then let Redocly CLI enforce the rules your team already agreed to. Keep humans in the loop for trade-offs, and treat automation as a safety net rather than a substitute for security review. + +## Learn more + +When you are ready to wire the deterministic side of the loop, start with [Explore Redocly CLI](https://redocly.com/docs/cli/) for installation, first commands, and how lint fits alongside bundling and preview workflows described in the broader [rulesets](https://redocly.com/docs/cli/rules) documentation. diff --git a/learn/ai-for-docs/ai-automate-documentation-reviews-pr-workflow.md b/learn/ai-for-docs/ai-automate-documentation-reviews-pr-workflow.md new file mode 100644 index 00000000..8209e0c5 --- /dev/null +++ b/learn/ai-for-docs/ai-automate-documentation-reviews-pr-workflow.md @@ -0,0 +1,101 @@ +--- +seo: + title: Use AI to automate documentation reviews in your PR workflow + description: How to wire AI checklist reviews into every doc pull request alongside Reunite previews and Redocly CLI lint so style, spec, and judgment stay in separate layers. +--- + +# Use AI to automate documentation reviews in your PR workflow + +Doc teams rarely lack review intent. They lack a default moment when review happens. Changes slip through because nobody re-reads the changelog, the new tutorial page, and the OpenAPI diff in one sitting before merge. The practical fix is to automate review at the pull request boundary: every doc-related PR gets the same fast checks before a human spends attention. + +This article shows how to combine an AI checklist pass on the diff, [Explore Redocly CLI](https://redocly.com/docs/cli/) lint in CI, and human approval in [Reunite](https://redocly.com/reunite) into three layers that do not compete for the same job. + +## What to run on every documentation pull request + +Scope automation to files the PR actually touches. Typical triggers include changelog entries, new or edited Markdown guides, navigation or sidebar edits, and OpenAPI files when the API surface changes. + +Split the work by failure type. Style and clarity checks belong in an AI step that reads prose against a short checklist. Contract checks belong in the [lint command](https://redocly.com/docs/cli/commands/lint) against the spec. Strategic questions about whether a page should exist at all stay with human reviewers in [review a pull request in Reunite](https://redocly.com/docs/realm/reunite/project/pull-request/review-pull-request). + +Keep each automated step under a few minutes on typical PRs. Long-running full-corpus reviews belong on a schedule, not on every push. + +## Three layers: AI, CLI, humans + +Think of the pipeline as three lanes that run in parallel where possible. + +The AI lane applies a versioned checklist to added or changed text. It flags vague changelog lines, inconsistent heading case, or missing backticks on HTTP verbs. It posts line-level suggestions when your platform supports them. + +The CLI lane runs [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) and your [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) against OpenAPI and any Markdown rules you encoded under [API standards and governance](https://redocly.com/docs/cli/api-standards). Lint output should fail the check, not merely warn, for rules you treat as merge blockers. + +The human lane uses Reunite visual diffs and threaded comments for judgment calls: Is this tutorial in the right place? Does marketing need to sign off? Does the example match behavior QA verified this week? + +None of these lanes replaces the others. AI is fast on prose patterns; lint is deterministic on schema shape; humans own context you did not paste into the prompt. + +## Redocly changelog reviews as a template + +[Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews) documents an internal flow you can mirror without copying our exact checklist. An author adds a changelog entry in the pull request. An automated step compares that entry to a short checklist and the surrounding PR context. If the entry passes, the bot confirms it. If not, it posts a suggested rewrite with a brief explanation before a human opens the diff. + +The before state is vague: "Fixed bug in API." The after state names the subsystem and symptom: authentication timeout in the OAuth2 flow when refresh tokens exceed the sixty-minute expiration window. That specificity is what you want every doc PR bot to enforce when changelog quality matters for release notes readers. + +Store the checklist in Git next to the docs so policy changes are reviewable like code. Point the bot at that file on every run so authors and automation share one source of truth. + +## How to wire the AI step in Git + +Pass the PR diff, the checklist file path, and explicit output rules. Ask for a table with file, rule id, quoted text, and suggested fix. Require a pass marker when no listed rule fails, even if the prose could be prettier elsewhere. + +Limit input tokens by scoping to changed hunks, not the entire repository. Post results as a check comment or review comment so authors see evidence beside the line. + +Avoid open-ended "improve this page" prompts on every commit. They rewrite voice and swamp reviewers with subjective edits. One checklist pass per push event is easier to trust than a roaming editor. + +For OpenAPI-only PRs, a separate prompt can ask for gap and consistency review as described in the same learn article, but keep that job separate from changelog style so failures are easy to route. + +## Where Reunite fits in the same workflow + +[Reunite](https://redocly.com/reunite) connects documentation work to Git branches, commits, and pull requests whether you use Redocly-hosted Git or an external provider. Authors [open a pull request in Reunite](https://redocly.com/docs/realm/reunite/project/pull-request/open-pull-request), invite reviewers, and use visual before-and-after previews on the Review tab so approvers see rendered pages, not only raw Markdown. + +Automated AI and lint checks should finish before you ask for human review, or at least post their status on the PR so reviewers know what is already clean. The [Reunite documentation](https://redocly.com/docs/realm/reunite/reunite) hub links editor, deployment, and PR tasks in one place. + +Treat Reunite as the conversation surface after machines narrow the diff. Bots surface checklist violations; humans decide what to merge. + +## Run Redocly CLI lint on the same pull request + +Add a CI job that runs `redocly lint` on the spec paths your repo owns. The post [consistent APIs with Redocly and GitHub Actions](https://redocly.com/blog/consistent-apis-redocly-github-actions) walks through wiring lint into GitHub Actions with annotations on the files authors changed. + +Use `--format=github-actions` or your platform equivalent so failures appear inline. Run lint on the same commit the AI step read so prose and schema feedback refer to one revision. + +When the model spots the same spec mistake repeatedly, promote it to a configurable lint rule so the next PR fails before the bot runs. + +## What automated review cannot decide + +Bots cannot know your unpublished roadmap, legal hold language, or whether a tutorial should be split for accessibility. They should not be the only reviewer on safety-critical runbooks. + +AI steps also drift if the checklist rots. Assign an owner to update the checklist when terminology changes, the same way you update lint rules. + +## Best practices + +1. Version the checklist and rulesets in Git and reference them by path in bot configuration. +2. Fail CI on lint errors you classify as blockers; keep AI output as suggestions until the checklist stabilizes. +3. Scope automated prose review to changed files in the PR to keep latency predictable. +4. Log false positives monthly and tune the checklist before you change models. + +## What this approach cannot replace + +This approach cannot replace editorial ownership, localization review, or security review of credential examples. It makes doc PRs predictable: machines enforce what you wrote down, humans decide what you did not. + +## How the pieces fit together + +```mermaid +graph TD + P[Doc PR opened] --> A[AI checklist on diff] + P --> L[Redocly CLI lint in CI] + A --> H[Human review in Reunite] + L --> H + H --> M[Merge when checks pass] +``` + +Each pull request triggers parallel machine lanes, then human approval on a narrowed diff. + +## Learn more + +When you want Git-backed docs, previews, and pull request review in one product surface, start with [Reunite](https://redocly.com/reunite) and the [Reunite documentation](https://redocly.com/docs/realm/reunite/reunite) hub for editor and PR workflows. + +Add [Explore Redocly CLI](https://redocly.com/docs/cli/) with the [lint command](https://redocly.com/docs/cli/commands/lint) and [API standards and governance](https://redocly.com/docs/cli/api-standards) when you want the same spec rules on every PR in CI. diff --git a/learn/ai-for-docs/ai-build-searchable-api-catalog.md b/learn/ai-for-docs/ai-build-searchable-api-catalog.md new file mode 100644 index 00000000..573d0558 --- /dev/null +++ b/learn/ai-for-docs/ai-build-searchable-api-catalog.md @@ -0,0 +1,134 @@ +--- +seo: + title: Use AI to build a searchable API catalog for your team + description: Enrich API metadata with AI at scale and publish a searchable Reef catalog your developers can browse or query in natural language. +--- + +# Use AI to build a searchable API catalog for your team + +A spreadsheet of service names is not a catalog. Developers need descriptions, owners, tags, and stable links they can search. You can use AI to enrich metadata across many OpenAPI files, then publish the result in Reef so the catalog stays current as specs change. That workflow extends the AI plus validation pattern in [How AI fits into modern API documentation](https://redocly.com/learn/ai-for-docs/ai-modern-api-docs). + +## Lists versus catalogs + +A list answers what is deployed. A catalog answers what it does, who owns it, and how to call it safely. Search fails when titles are opaque (`internal-svc-7`) or when the same product has three names across repos. Metadata is the difference between findability and guesswork. + +Think of search as matching intent to records. Intent might be I need to refund a subscription or Which API owns webhooks. Without summaries and tags, search falls back to filename guessing. A catalog row should read like a helpful librarian card, not like an infrastructure ticket title. + +## Metadata AI can enrich safely + +Models are strong at drafting short descriptions from paths and schemas, proposing tags from domain language, and normalizing display names when you supply a style note. They are weak at inventing owners or SLAs. Paste real ownership from your service registry when you have it, and ask the model only to format or shorten. + +Fields worth enriching in bulk: + +- Human-readable summary (one to two sentences) +- Domain tags (`payments`, `identity`) +- Lifecycle stage (`experimental`, `stable`, `deprecated`) +- Links to primary OpenAPI file and runbooks + +Add a contact or team channel when your service catalog already stores it. Search results that end in a dead end teach developers to ignore the catalog. + +## Prompt skeleton for bulk enrichment + +```markdown {% process=false %} +You are enriching API catalog metadata for internal developers. + +Rules: +- Do not invent owners or on-call handles; leave blank if missing. +- Use sentence case for titles. +- Keep summaries under 40 words. + +For each API row below, return JSON with: title, summary, tags, lifecycle. + +[paste table of api_id, path_prefix, openapi_excerpt, owner_if_known] +``` + +Review JSON in a pull request like any other generated content. + +## Before and after on catalog fields + +Before: + +```yaml {% process=false %} +title: orders-svc +description: "" +``` + +After: + +```yaml {% process=false %} +title: Orders API +description: Create and track customer orders for the retail storefront. +tags: [orders, commerce] +lifecycle: stable +``` + +The after block still needs a human to confirm accuracy against the live service. + +## Ingest, enrich, and publish + +Collect specs with [Scout documentation](https://redocly.com/docs/realm/scout) and [What is Scout?](https://redocly.com/docs/realm/scout/what-is-scout) so enrichment starts from files in git, not from stale exports. Configure how APIs appear in the portal using [API catalog configuration](https://redocly.com/docs/realm/config/catalog-classic). Tune findability with [Search configuration](https://redocly.com/docs/realm/config/search) once metadata lands. + +```mermaid +graph LR + A[OpenAPI in repos] --> B[Scout collect] + B --> C[AI metadata pass] + C --> D[Human review] + D --> E[Reef catalog publish] +``` + +Re-run enrichment when major paths change, not on every typo fix. + +## Search and natural-language questions + +Structured search uses tags and titles. Natural-language questions work better when summaries mention tasks (`refund a subscription`) not only resource names. The [API catalogs for agentic software](https://redocly.com/blog/api-catalogs-agentic-software) post describes why rich metadata helps both people and agents choose the right API on the first try. + +You do not need a custom chatbot on day one. Start with faceted search by tag and owner, then add assistant features when metadata quality is stable. If answers cite the wrong API, fix the catalog row before tuning the model. Garbage in still produces confident wrong answers. + +### Questions to test after publish + +Ask five colleagues to find an API without Slack help: + +1. How do I create a webhook for billing events? +2. Which API owns user invitations? +3. Where is the sandbox base URL documented? +4. What is deprecated in payments this quarter? +5. Who owns the identity service on call? + +Misses become metadata tickets, not one-off doc edits buried in a random repo. + +### Checklist before you turn on broad search + +- Every catalog entry links to a canonical OpenAPI file +- Deprecated APIs are labeled and point to replacements +- Owners or team channels are present for stable APIs +- Sensitive internal-only APIs are flagged in metadata + +## Best practices + +Batch enrich by domain so reviewers stay in context. + +Keep a banned-phrase list (internal codenames) in the prompt. + +Diff enriched YAML in CI so drift is visible. + +Pair catalog updates with Scout collection schedules. + +Assign a metadata owner per domain who approves AI suggestions weekly. + +Store enrichment prompts in git next to the glossary so changes are reviewable. + +When an API ships, block merge unless catalog metadata updates in the same pull request as the OpenAPI change. + +## Limits of generated metadata + +Generated text can misstate behavior if the spec is thin. Models may over-tag APIs when prompts are vague. Search quality still depends on engineers maintaining specs after enrichment. + +If your organization also runs API design reviews, feed catalog gaps back into those reviews. A missing description in the catalog often means the OpenAPI `summary` was empty when the service shipped. Fixing upstream specs keeps AI enrichment from repeating the same blank template every quarter. + +## Summary + +Treat catalog metadata as a product: collect specs, enrich with grounded AI, review in git, and publish in Reef with search tuned for how your developers ask questions. Revisit catalog quality when teams complain they cannot find an API, not only when Scout adds new repositories. + +## Learn more + +[Reef](https://redocly.com/reef) hosts the searchable catalog and Scout collection so enriched metadata stays tied to the repositories your teams already maintain. diff --git a/learn/ai-for-docs/ai-check-terminology-consistency-across-docs.md b/learn/ai-for-docs/ai-check-terminology-consistency-across-docs.md new file mode 100644 index 00000000..ea9a00c2 --- /dev/null +++ b/learn/ai-for-docs/ai-check-terminology-consistency-across-docs.md @@ -0,0 +1,118 @@ +--- +seo: + title: Use AI to check terminology consistency across your docs + description: Audit docs for conflicting terms with AI, encode a canonical glossary in Redocly CLI lint rules, and single-source definitions with Reunite remote content. +--- + +# Use AI to check terminology consistency across your docs + +The same product becomes an account, a tenant, and an organization in different guides. Readers notice, and linters do not catch prose drift by default. You can run an AI terminology audit, agree on a canonical glossary, encode forbidden variants in Redocly CLI rules, and host shared definitions with Reunite remote content. The review rhythm matches [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews), but the checklist here focuses on language rather than API shape. + +## How the same concept gets three names + +Teams write docs in parallel. Marketing prefers customer-friendly words while reference docs keep engineer shorthand. Acquisitions import whole doc sets with their own nouns. Without a glossary, every writer makes a reasonable local choice and the corpus diverges. + +Terminology drift also shows up inside OpenAPI `description` fields, error messages rendered in docs, and UI strings pasted into guides. An audit that scans only marketing pages will miss conflicts sitting next to schema tables. Include both prose pages and spec excerpts in the first pass. + +## AI audit prompt for terminology + +Paste excerpts or file paths with a short domain note. Ask for conflicts, not rewrites, in the first pass. + +```markdown {% process=false %} +You are auditing documentation terminology for [product domain]. + +Canonical terms we prefer: +- organization (not tenant, not account) for B2B workspaces +- member (not user) for people inside an organization + +Scan the excerpts below and return a table: +| term_used | preferred_term | file_or_section | severity | + +Do not rewrite prose yet. + +[paste markdown excerpts] +``` + +Severity helps writers triage before you open a hundred tickets. + +## Building a canonical glossary + +Convert the audit table into a one-page glossary with definition, allowed synonyms, and forbidden variants. Store it in git. Link it from your contributor guide. Keep entries short so writers actually read them. + +Example entry: + +```markdown {% process=false %} +## organization +Definition: A B2B customer workspace that owns subscriptions. +Use: organization +Avoid: tenant, account (unless referring to billing account) +``` + +## Encoding terms as CLI rules + +Subjective audits do not scale in CI. After humans agree on terms, express checks with [configurable rules](https://redocly.com/docs/cli/rules/configurable-rules) in your ruleset. Start from the [recommended ruleset](https://redocly.com/docs/cli/rules/recommended) and extend. Run the [lint command](https://redocly.com/docs/cli/commands/lint) on pull requests that touch docs or OpenAPI descriptions so violations fail before merge. + +Configurable rules work well for description fields and summary strings where the same forbidden token should never appear. They cannot understand context-heavy cases (`account` in a banking doc may be correct). Keep a short exception list in the rule comments. + +The [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) walks through first-time setup if your repository has no `redocly.yaml` yet. + +### Example policy you can express + +| Forbidden in summaries | Preferred | Notes | +|------------------------|-----------|-------| +| tenant | organization | B2B workspace | +| user | member | people inside an org | +| webhook URL | webhook endpoint | align with UI copy | + +Start with three to five high-impact swaps. Expand after false positives are understood. + +```mermaid +graph LR + A[AI terminology audit] --> B[Glossary in git] + B --> C[CLI configurable rules] + C --> D[CI lint on PRs] + B --> E[Reunite remote content] + E --> F[Published docs] +``` + +Remote content keeps definitions synchronized with the glossary file. + +## Reunite remote content for single sourcing + +When a term appears in fifty pages, editing each file by hand fails. [Remote content](https://redocly.com/docs/realm/reunite/project/remote-content/remote-content) lets Reunite pull shared snippets from a canonical repository. Writers edit the glossary fragment once; pages include it by reference. Onboard authors with [start with the Reunite editor](https://redocly.com/docs/realm/get-started/start-reunite-editor) and point them at [Reunite](https://redocly.com/reunite) for the wider workflow. + +Use remote content for definitions and boilerplate, not for entire guides, so diffs stay readable. + +Version the glossary file with semver or dates in the filename when terms change often. Remote content consumers should pin to a tag until they update references deliberately. + +## Best practices + +Run terminology audits after rebrands or major UI copy changes. + +Separate audit (find conflicts) from rewrite (fix prose) into two PR types. + +Pair CLI bans with positive examples in the glossary. + +Review false positives monthly and narrow rules instead of disabling lint. + +Invite support and developer relations to the glossary review so customer-facing language matches docs. + +Publish the glossary URL in your pull request template checklist for doc authors. + +When remote content updates a definition, run lint on consuming projects the same day. + +Export audit tables to CSV so product and support can comment without learning git syntax. + +## What lint cannot catch + +Rules excel at forbidden tokens in machine-readable fields. They struggle with ambiguous sentences where both terms are valid in context. AI audits can over-report colloquial phrases that stakeholders want to keep. Legal and brand still own trademark capitalization. + +For narrative docs outside OpenAPI, run a lighter periodic AI audit even when CLI rules pass. Markdown guides can still mix customer and member in the same paragraph. Schedule that pass after major releases when new screenshots import fresh UI strings. + +## Summary + +Use AI to surface terminology drift, publish a short canonical glossary, enforce agreed bans with Redocly CLI in CI, and single-source definitions through Reunite remote content so the next writer does not reintroduce a third name for the same thing. Treat terminology like API versioning: visible, owned, and reviewed on a schedule. + +## Learn more + +[Explore Redocly CLI](https://redocly.com/docs/cli/) to wire configurable terminology rules into the same lint workflow you already use for OpenAPI validation. diff --git a/learn/ai-for-docs/ai-detect-drift-docs-live-api.md b/learn/ai-for-docs/ai-detect-drift-docs-live-api.md new file mode 100644 index 00000000..3594649f --- /dev/null +++ b/learn/ai-for-docs/ai-detect-drift-docs-live-api.md @@ -0,0 +1,119 @@ +--- +seo: + title: Use AI to detect drift between your docs and your live API + description: Use Respect scheduled Arazzo workflows to catch live API drift, then use AI to interpret alerts and draft doc updates your team can review. +--- + +# Use AI to detect drift between your docs and your live API + +Your OpenAPI file and your developer portal can be perfect on merge day and still lie to customers two sprints later when an engineer ships a new status code, renames a field, or changes pagination defaults without updating prose. Drift is a timing problem. Respect gives you scheduled truth checks against live endpoints; AI helps you turn alerts into readable doc diffs your writers can accept or reject. + +## Why docs fall behind production + +Teams optimize for shipping features, not synchronizing every paragraph with deployment trains. Spec-first shops still skip tutorial updates. Doc-first shops still miss sandbox-only behavior. Even strong lint in CI only validates files in Git, not what runs behind the load balancer tonight. + +Drift shows up as support tickets ("your sample returns 404"), failed customer scripts, and AI agents that confidently cite outdated examples. You need monitoring that compares behavior to the contract you publish, plus a human-readable path from failure to doc fix. + +## Catch behavioral drift with Respect + +[Respect](https://redocly.com/respect) runs API workflows described in Arazzo against real environments. You define steps such as obtain token, create resource, list with pagination, and assert status codes and JSON shapes. Schedule those workflows against staging and production, and route failures to Slack or email the way you route test failures. + +[Respect use cases](https://redocly.com/docs/respect/use-cases) cover contract testing in pull requests and ongoing monitoring after deploy. The same workflow file can gate a release in CI and run hourly to detect silent regressions. + +```mermaid +graph LR + S[Published OpenAPI and docs] --> W[Arazzo workflow] + W --> L[Live API] + L -->|Pass| OK[No alert] + L -->|Fail| A[Respect alert] + A --> AI[AI summarizes drift] + AI --> PR[Writer opens doc PR] +``` + +[Documenting multiple APIs using Arazzo](https://redocly.com/learn/arazzo/documenting-multiple-apis-using-arazzo) explains how to model multi-step flows that lint alone cannot express. When a Respect step expects page[size] but production now expects pageSize, you have a concrete diff to chase in reference and guides. + +## Sample alert and what to record + +A useful alert bundles environment, step name, expected assertion, actual response snippet, and workflow version. Avoid screenshots alone; writers need copyable JSON. + +Example alert body (illustrative): + +```text +Workflow: signup-smoke +Step: list-orders page 2 +Expected: 200 with body.links.next +Actual: 200 with body.pagination.nextCursor +Environment: production-eu +``` + +Store alerts in your ticket system with labels docs-drift and api-drift so teams know whether to fix code, spec, or prose first. + +## Use AI to interpret alerts and draft updates + +AI does not replace Respect assertions. It accelerates triage: classify whether the spec, implementation, or documentation is wrong, then propose edits grounded in artifacts you paste. + +```markdown {% process=false %} +You are helping a technical writer fix documentation drift. + +Inputs: +1. Respect alert (below) +2. Excerpt from current OpenAPI for the affected operation +3. Excerpt from current doc page + +Tasks: +- State the most likely source of drift (spec, implementation, docs) +- List doc sentences that are now false +- Propose revised paragraphs and example JSON +- Flag if OpenAPI must change before docs + +Do not invent endpoints. If uncertain, ask one clarifying question. + +Alert: +[paste] + +OpenAPI: +[paste] + +Docs: +[paste] +``` + +Review output like any generated draft. If production is wrong, fix the service and add Respect coverage so the bug cannot return quietly. If production is right, update OpenAPI first when your portal is spec-driven, then refresh tutorials. + +## Alert-to-fix workflow your team can adopt + +1. Respect fails on schedule; on-call acknowledges within SLA. +2. Owner pastes alert, spec slice, and doc slice into the prompt above. +3. Writer opens a pull request with doc changes; API owner opens a parallel change if schema changed. +4. Merge after [lint command](https://redocly.com/docs/cli/commands/lint) passes on the updated spec and a repeat Respect run is green. +5. Add a one-line changelog entry for external developers when behavior visible to customers changed. + +[API contract testing with Arazzo](https://redocly.com/blog/api-contract-testing-arazzo) describes how teams wire similar flows into CI; the same files reduce drift between "works in staging PR" and "works Tuesday night in prod." + +## Keep docs and spec in the same change train + +When Respect fails, resist fixing only the portal copy while the OpenAPI file stays stale. Generated reference from Redoc and similar tools will overwrite manual edits on the next build. Treat the spec as the contract your customers export, update it first when production behavior is correct, then refresh guides and task-based examples that [Use AI as a usability tester](https://redocly.com/learn/ai-for-docs/ai-usability-testing) exercises in your smoke suite. + +For teams comparing monitoring approaches, [tools for API testing in 2025](https://redocly.com/learn/testing/tools-for-api-testing-in-2025) summarizes how contract tests, sandboxes, and observability fit together; Respect slots into the contract and monitoring lane rather than replacing exploratory QA. + +## Best practices + +Version Arazzo workflows in Git beside the OpenAPI they exercise. + +Test sandboxes and production separately; drift messages differ when only one region changed. + +Keep example payloads in docs generated from fixtures Respect already asserts when possible. + +When AI proposes doc fixes, require citations to alert lines so reviewers see the evidence chain. + +## What AI cannot verify alone + +Models do not execute HTTP requests in your VPC unless you give them tools to do so. They may rationalize a wrong field name if the alert is incomplete. Respect remains the source of behavioral truth; AI is editorial acceleration on top. + +## Summary + +Schedule Respect workflows against live APIs to detect drift early, capture alerts with enough detail to reproduce failures, and use AI to draft spec and doc updates humans merge with normal review. The goal is not fewer alerts; it is shorter time from alert to accurate public docs. + +## Learn more + +To run scheduled Arazzo workflows, monitor live endpoints, and get notified when behavior diverges from your spec, start with [Explore Respect](https://redocly.com/respect) and [Respect use cases](https://redocly.com/docs/respect/use-cases). diff --git a/learn/ai-for-docs/ai-enforce-api-style-guide-at-scale.md b/learn/ai-for-docs/ai-enforce-api-style-guide-at-scale.md new file mode 100644 index 00000000..31518ea6 --- /dev/null +++ b/learn/ai-for-docs/ai-enforce-api-style-guide-at-scale.md @@ -0,0 +1,142 @@ +--- +seo: + title: Use AI to enforce your API style guide at scale + description: How to turn a prose API style guide into Redocly CLI lint rules, run them across many OpenAPI files, and handle cases where AI suggestions and deterministic rules disagree. +--- + +# Use AI to enforce your API style guide at scale + +A long wiki style guide does not stop the next team from shipping inconsistent operationId values across dozens of services, so you need prose for intent and lint rules for pass-or-fail checks, with AI bridging the gap to a redocly.yaml ruleset you run on every OpenAPI file in CI. This article shows how to condense your guide into a checklist, draft configurable rules with a model, scale enforcement with Redocly CLI, and keep human judgment where automation and the model disagree. + +## Why a style guide and lint rules serve different jobs + +Your style guide answers why and when. It covers naming philosophy, error shape preferences, and when to break a pattern for backward compatibility. Readers learn judgment from examples and narrative. + +Lint rules answer whether this file violated a stated rule right now. They run the same way on every pull request, across hundreds of paths, without re-reading a PDF. [API standards and governance](https://redocly.com/docs/cli/api-standards) describes how [Explore Redocly CLI](https://redocly.com/docs/cli/) applies those checks locally and in continuous integration with one shared configuration. + +If you only publish prose, standards drift as headcount grows. If you only ship lint without a readable guide, authors fix red squiggles without understanding the design goal. Keep both artifacts linked: each configurable rule should trace back to a checklist line your guide already explains. + +## Condense prose into a checklist first + +[Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews) makes the same point for documentation style: a one-page checklist beats a fifty-page manual for consistent review. Apply that shape to API design rules before you ask a model to write YAML. + +Replace paragraphs like "operation identifiers should be clear and consistent" with inspectable lines: + +```markdown {% process=false %} +- [ ] Every operation has an operationId +- [ ] operationId uses camelCase +- [ ] Path parameters use snake_case in the spec +- [ ] Every operation declares security when the API uses OAuth2 +- [ ] Error responses include a machine-readable code field +``` + +If your organization is still debating standards, the [API guidelines builder](https://redocly.com/api-governance) and the post on [build your own API guidelines](https://redocly.com/blog/build-your-own-api-guidelines) recommend answering only the questions that matter now and expanding the ruleset later. A short checklist is easier for AI to map to assertions than an unfocused workshop output. + +## Prompt AI to draft Redocly CLI rules + +Give the model three inputs: the checklist, one representative OpenAPI excerpt that currently fails a few lines, and the Redocly [configurable rules](https://redocly.com/docs/cli/rules/configurable-rules) shape (subject, assertions, severity). Ask for output as a rules block only, with one rule name prefixed with rule/ per checklist item that can be expressed as an assertion. + +```markdown {% process=false %} +You are translating an API style checklist into Redocly CLI configurable rules. + +Checklist: +[paste checklist] + +Example OpenAPI excerpt with known violations: +[paste yaml] + +For each checklist item that can be checked deterministically on an OpenAPI node: +1. Propose a rule name prefixed with rule/ +2. Set subject type and property +3. Choose assertions (casing, defined, pattern, enum, nonEmpty) +4. Set severity: error for merge blockers, warn for gradual adoption +5. Skip items that require human judgment and list them under manual_only + +Return valid YAML for the rules section only. +``` + +Review the draft like any generated code. AI may overfit to the sample file or set severity too aggressively for legacy APIs. Treat the output as a first pull request, not production config. + +## Before and after: one prose rule becomes YAML + +Prose rule: Operation IDs must use camelCase so generated SDK methods read naturally. + +Configurable rule the model might propose: + +```yaml {% process=false %} +rules: + rule/operationId-camelCase: + subject: + type: Operation + property: operationId + assertions: + casing: camelCase + message: operationId must use camelCase per API style guide section 4.2 + severity: error +``` + +Lint output on a violating spec surfaces the same line every time, which is what scale requires. Authors click from CI annotation to the rule name, then to the guide section cited in message. + +For rules already covered by [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules), prefer extending the [recommended ruleset](https://redocly.com/docs/cli/rules/recommended) and toggling severity instead of duplicating logic. Reserve configurable rules for standards specific to your organization. + +## Run the ruleset across many APIs + +Start from a shared redocly.yaml at the repo root or in a dedicated standards repository. The [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) shows how extends pulls in recommended, then your custom YAML, then per-rule overrides. + +```yaml {% process=false %} +extends: + - recommended + - ./org-api-standards.yaml + +rules: + security-defined: warn +``` + +Publish org-api-standards.yaml as a reusable package so many microservices import the same file version. Use the apis block when one legacy surface needs looser rules while new APIs stay strict: point each API root at its OpenAPI file and override only the rules that differ. + +Wire [lint command](https://redocly.com/docs/cli/commands/lint) into CI on every OpenAPI path you own. Local runs before push catch the same failures developers see in the pipeline. When the model flags a recurring violation in review but lint stays green, that is a signal to promote the checklist line into a new rule entry. + +```mermaid +graph LR + G[Style guide checklist] --> A[AI drafts rule YAML] + A --> R[redocly.yaml plus org standards] + R --> L[redocly lint local] + R --> C[redocly lint in CI] + C --> F[Fix or waive with human owner] +``` + +The flow keeps prose standards, generated rules, and deterministic enforcement in one loop you can repeat when the guide changes. + +## When AI and lint disagree + +Disagreement usually falls into three buckets. + +Subjective clarity: the model says a description is vague; lint passes because description is non-empty. Keep that in AI-assisted review or an editorial checklist, not in redocly.yaml, unless you can write a tight pattern assertion without false positives. + +Legacy exceptions: lint fails on an API you cannot change this quarter. Lower severity to warn for that API in the per-API block, or disable one rule with a tracked ticket. Do not delete the rule globally. + +Overstrict generated rules: the model proposes pattern assertions that reject valid paths your guide allows. Humans trim the assertion or narrow the where clause. [Configurable rules](https://redocly.com/docs/cli/rules/configurable-rules) documentation covers optional where filters when the rule should apply only to certain operations. + +Human judgment stays final for trade-offs the guide describes in prose. Lint owns what you encoded. AI helps you draft and refresh encoding when the guide evolves. + +## Best practices + +1. Version the checklist and redocly.yaml in Git; reference the same commit in AI prompts and CI. +2. Start with warn on new rules for brownfield APIs; promote to error when violation counts trend to zero. +3. Ask the model for a manual_only list so subjective standards do not become brittle patterns. +4. Re-run translation when the guide changes, the same way you update tests when requirements change. +5. Combine AI review for gaps and naming clarity with CLI lint for enforceable shape, as [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews) recommends. + +## What lint cannot replace + +Lint cannot judge roadmap priority, legal wording in descriptions, or whether an endpoint should exist at all. It cannot verify that your examples match production behavior without separate contract tests. It will not fix an API team that never adopted the guide in the first place. + +Use automation to make agreed standards unavoidable, workshops to reach agreement, and humans when the guide itself needs to change. + +## The balance + +A thin checklist, a reviewed redocly.yaml, and CI that runs the same rules on every service turns your style guide from shelfware into a default developers meet before merge. + +## Learn more + +To encode standards with built-in, configurable, and custom rules, tune severity per API, and run lint locally and in CI, start with [Explore Redocly CLI](https://redocly.com/docs/cli/) and [API standards and governance](https://redocly.com/docs/cli/api-standards). diff --git a/learn/ai-for-docs/ai-enforce-tone-style-consistency-across-docs.md b/learn/ai-for-docs/ai-enforce-tone-style-consistency-across-docs.md new file mode 100644 index 00000000..2a970d64 --- /dev/null +++ b/learn/ai-for-docs/ai-enforce-tone-style-consistency-across-docs.md @@ -0,0 +1,86 @@ +--- +seo: + title: Use AI to enforce tone and style consistency across docs + description: How tone drifts across authors, why a one-page checklist beats a style manual for LLM reviews, and how Reunite pull requests plus Redocly CLI rules keep prose aligned before merge. +--- + +# Use AI to enforce tone and style consistency across docs + +Documentation sets rarely fail because nobody cares about tone. They fail because ten caring people each wrote a page under pressure and nobody had time to re-read the whole corpus before release. A large language model can scan many files for the same handful of rules in minutes. + +It will still miss strategy and brand nuance if you hand it a fifty-page style guide. The practical pairing is a short checklist in the prompt, a Git pull request in [Reunite](https://redocly.com/reunite) so every change gets a diff and a preview, and [Explore Redocly CLI](https://redocly.com/docs/cli/) rules for anything you can state as a repeatable pattern. + +This article follows the catalog scope: why drift happens, how to brief AI with a condensed checklist, a concrete internal changelog workflow you can read on our learn site, and how to wire reviews into PRs. + +## Why tone drifts even when the team agrees on standards + +Contributors ship under different deadlines, copy from older pages that predate the latest terminology, and inherit templates that never matched the style guide. Editors also optimize for clarity in isolation, which produces perfectly good sentences that still read like five products in one handbook. + +Drift is a coordination problem more than a motivation problem. You need a lightweight signal on every change, not a quarterly read-through that arrives too late. + +## Give the model a checklist, not a prose style guide + +Long manuals dilute attention for humans and for models alike. The learn article [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews) argues that a one-page checklist outperforms multi-page prose rules because each line is actionable in a single pass. + +Translate your house style into ten to fifteen binary checks. Examples include present tense for shipped behavior, second person for procedural steps, code literals in backticks, banned hedge words, and heading case rules. Paste that list above the Markdown you want reviewed, then ask for a table with columns for file path, rule id, quote of the offending text, and a concrete rewrite. + +Ask the model to return "pass" when a section violates no listed rule, even if it could be prettier. That reduces noise from subjective taste that belongs in human review. + +## A real example: changelog entries before merge + +The same learn article documents how Redocly treats changelog PRs. The flow stays small on purpose. The author writes the entry, an automated review compares it to a short internal checklist and the surrounding PR context, and the bot either confirms the entry or posts a suggested rewrite with an explanation before a human spends time on it. + +You can reuse that shape without copying our exact checklist. What matters is that the model receives the diff, the checklist, and permission to quote lines directly so reviewers see evidence, not vibes. + +## How Reunite turns reviews into a default step in Git + +[Reunite](https://redocly.com/reunite) is built around Git-backed projects, an editor, and the social mechanics of review. The docs hub under [Reunite documentation](https://redocly.com/docs/realm/reunite/reunite) links to tasks such as [Get started with the Reunite editor](https://redocly.com/docs/realm/get-started/start-reunite-editor) and [Open a pull request in Reunite](https://redocly.com/docs/realm/reunite/project/pull-request/open-pull-request). + +Those pages are where previews and threaded comments belong before merge. + +Put the checklist in your PR template or bot comment so authors see it before they ask for review. Keep the AI step fast: one checklist pass per commit is easier to trust than an open-ended prompt that rewrites whole files. + +## Where Redocly CLI still matters + +Some style rules are subjective, but others are mechanical once you write them down: forbidden terminology, required front matter keys, links that must stay relative, or headings that must match a pattern. Those belong in [API standards and governance](https://redocly.com/docs/cli/api-standards) as lint, not as model judgment. + +Use the [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules), extend [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) where they already fit, and add [configurable rules](https://redocly.com/docs/cli/rules/configurable-rules) when you need assertions on headings, metadata, or repeated phrases. The model can propose new rules after it spots the same mistake three times in one month. Engineers encode the rule so the fourth time never ships. + +## What AI cannot judge + +Models cannot decide whether a feature name should align with marketing for the next launch, whether legal needs to approve a sentence, or whether a tutorial should be split for accessibility. They also should not be the only reviewer on safety-critical instructions. + +Use AI to enforce the checklist you already agreed as a team. Use humans for trade-offs, narrative arc, and anything that depends on roadmap context you did not paste into the prompt. + +## Best practices + +1. Version the checklist in Git next to the docs so changes to tone policy are reviewable like code. +2. Scope each automated pass to the files touched in the PR so latency stays low and suggestions stay local. +3. Log false positives and tune the checklist before you tune the model temperature. +4. Pair every AI comment with a human approval step until the checklist stabilizes. + +## What this approach cannot replace + +This approach cannot replace editorial ownership of narrative voice, localization review, or accessibility audits that require assistive technology. It reduces noisy inconsistency; it does not choose your brand story for you. + +## How the pieces fit together + +```mermaid +graph LR + C[Checklist in repo] --> A[AI review on PR] + A --> R[Human reviewer in Reunite] + R --> M[Merge to main] + M --> L[Redocly CLI lint in CI] + + style A fill:#e1f5ff + style R fill:#fff4e1 + style L fill:#e8f5e9 +``` + +Checklists steer the model, Reunite carries the conversation on a real diff, and CLI lint keeps mechanical rules from regressing after merge. + +## Learn more + +When you want Git-backed writing, previews, and pull requests in one place, start with [Reunite](https://redocly.com/reunite) and the linked [Reunite documentation](https://redocly.com/docs/realm/reunite/reunite) for editor and PR tasks. + +When you are ready to encode the rules that should never depend on model mood, add [Explore Redocly CLI](https://redocly.com/docs/cli/) with [API standards and governance](https://redocly.com/docs/cli/api-standards) and [configurable rules](https://redocly.com/docs/cli/rules/configurable-rules) so the same checks run locally and in CI. diff --git a/learn/ai-for-docs/ai-find-duplicate-underused-apis.md b/learn/ai-for-docs/ai-find-duplicate-underused-apis.md new file mode 100644 index 00000000..d09270cd --- /dev/null +++ b/learn/ai-for-docs/ai-find-duplicate-underused-apis.md @@ -0,0 +1,103 @@ +--- +seo: + title: Use AI to find duplicate and underused APIs in your codebase + description: Combine Reef API Scout discovery with structured AI review to spot overlapping endpoints and low-use services before you consolidate. +--- + +# Use AI to find duplicate and underused APIs in your codebase + +Large organizations often discover the same capability twice because teams ship in parallel. You can run a discovery audit that starts with inventory from Reef API Scout, then uses a model to group similar endpoints and flag APIs with weak ownership or usage signals. The pairing keeps facts grounded while AI handles pattern matching at scale, which matches the broader lifecycle in [How AI fits into modern API documentation](https://redocly.com/learn/ai-for-docs/ai-modern-api-docs). + +## Why API sprawl shows up late + +Microservices, acquisitions, and partner integrations all add routes. Without a catalog, duplicate payment or profile APIs can coexist for years. Underused services still incur security review and on-call load. The pain appears when a new team rebuilds something that already exists, or when compliance asks for a complete API list you cannot produce quickly. + +Sprawl is rarely malicious. Two product lines may both need a customer record, so each ships a `/customers` surface with slightly different fields. A partner integration copies an internal spec and never syncs again. Platform teams inherit repos they did not author, so nobody feels safe deleting the older variant. Discovery work pays off when you can show overlap with evidence instead of asking teams to merge on faith alone. + +## What Scout gives you before AI + +[What is Scout?](https://redocly.com/docs/realm/scout/what-is-scout) describes how Redocly Scout collects API definitions from repositories so you are not guessing from memory. Deploy and operate collection using the [Scout documentation](https://redocly.com/docs/realm/scout) and review [Scout use cases](https://redocly.com/docs/realm/scout/use-cases) for common estate layouts. Scout answers which APIs exist and where their specs live. It does not by itself decide which duplicates to retire. + +Treat Scout output as the allowlist for AI review. If a path never appears in inventory, the model should not invent it. + +## Inputs for an AI-assisted duplicate review + +Export or paste a table of services with path prefixes, OpenAPI titles, owners, and optional traffic or consumer counts when your platform provides them. Add business context in a short paragraph: which domains are strategic, which systems are legacy-only, and whether multiple versions are intentional. + +> Example row: `payments-v2` POST `/charges` and `billing-legacy` POST `/payment/charges` both owned by different teams, last deploy 18 months apart. + +## Prompt skeleton for overlap and usage signals + +```markdown {% process=false %} +You are reviewing an API inventory for duplicate or underused APIs. + +Given the table below: +1. Group endpoints that appear to implement the same capability (name the cluster). +2. Flag APIs with no clear owner or stale metadata. +3. Note version pairs that look like unmigrated duplicates. +4. List APIs that look underused based on the usage column (if present). +5. Suggest one consolidation question per cluster for human owners. + +[paste inventory table] +``` + +Keep clusters small enough that owners can respond in one meeting. + +## Signals models often surface + +Models frequently cluster near-duplicate paths that differ only by prefix or verb choice. They also highlight parallel major versions when v1 and v2 both accept writes. Shadow APIs appear when OpenAPI exists in a repo but the service is not linked from any catalog entry. Underuse shows up when consumer counts are zero or when an API has rich spec text but no recent deploys. Treat every cluster as a hypothesis until owners confirm. + +### Duplicate patterns worth naming in the prompt + +Ask the model to label clusters so owners recognize the pattern quickly: + +| Pattern | What it looks like | Typical owner action | +|---------|-------------------|----------------------| +| Twin resources | Two CRUD surfaces on the same noun | Pick one canonical API, deprecate the other | +| Version fork | v1 and v2 both writable | Freeze v1, document migration | +| Shadow spec | OpenAPI in git, no runtime owner | Archive or attach to a service | +| Dormant API | No consumers in telemetry | Sunset or merge into a shared platform API | + +When telemetry is missing, say so in the prompt. The model should flag uncertainty instead of ranking APIs as unused without data. + +## Turning findings into a consolidation backlog + +Rank clusters by customer impact and operational cost, not by spec similarity alone. For each accepted duplicate, record the canonical API, the deprecation window, and the doc redirect plan. Publish the result in your catalog configuration so search surfaces the winner, as described in [API catalog configuration](https://redocly.com/docs/realm/config/catalog-classic). The [API catalogs for agentic software](https://redocly.com/blog/api-catalogs-agentic-software) article explains why a single searchable layer matters when both humans and agents consume your estate. + +```mermaid +graph LR + A[Scout inventory] --> B[AI cluster review] + B --> C[Owner decisions] + C --> D[Reef catalog update] + D --> E[Deprecate duplicates] +``` + +The loop runs quarterly or after major acquisitions, not only once. + +## Best practices + +Start from collected specs, not from chat memory about what exists. + +Ask owners for one sentence on why two similar APIs both exist before you schedule decommission. + +Track consumer migrations explicitly when you retire a duplicate. + +Log model clusters with links to spec files so auditors can reproduce the review. + +Share audit results in the same channel where architects already discuss standards, so consolidation does not feel like an surprise security review. + +Time-box AI review to clusters under twenty APIs per pass. Larger batches produce vague groupings. + +When you publish winners in the catalog, add a `deprecated` or `successor` field in metadata so search surfaces the replacement immediately. + +## What discovery cannot replace + +AI does not see private traffic dashboards unless you paste aggregates, and it cannot sign deprecation notices for partner APIs. Scout coverage is only as complete as the repositories you connect. Political ownership disputes still need human negotiation. + +## Summary + +Use Scout to inventory the estate, use structured AI passes to propose duplicate and underuse clusters, then let owners decide what to merge. Publish the canonical APIs in Reef so the next team finds one front door instead of three. + +## Learn more + +[Reef](https://redocly.com/reef) brings API Scout discovery and catalog publishing together so duplicate reviews turn into a maintained source of truth rather than a one-off spreadsheet. diff --git a/learn/ai-for-docs/ai-find-gaps-documentation-coverage.md b/learn/ai-for-docs/ai-find-gaps-documentation-coverage.md new file mode 100644 index 00000000..47555897 --- /dev/null +++ b/learn/ai-for-docs/ai-find-gaps-documentation-coverage.md @@ -0,0 +1,115 @@ +--- +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. +--- + +# Use AI to find gaps in your documentation coverage + +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. + +## Two kinds of gaps + +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. + +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. + +```mermaid +graph TD + O[OpenAPI plus docs set] --> L[Redocly CLI lint] + O --> A[AI workflow review] + O --> R[Respect live workflows] + L --> S[Structural gap list] + A --> W[Workflow gap list] + R --> M[Runtime mismatch alerts] +``` + +## Find structural gaps with Redocly CLI + +[Built-in rules](https://redocly.com/docs/cli/rules/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. + +When your standard goes further, [configurable rules](https://redocly.com/docs/cli/rules/configurable-rules) express org-specific coverage: require examples on path parameters, forbid empty tag descriptions, or enforce a minimum response set per operation. The [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) shows how to extend recommended with a shared org-api-standards.yaml file every repository imports. + +Run [lint command](https://redocly.com/docs/cli/commands/lint) 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. + +### Coverage checklist for lint + +```markdown {% process=false %} +- [ ] Every operation has summary and description +- [ ] Path and query parameters include description and example where required +- [ ] 4xx responses documented for authenticated routes +- [ ] security schemes defined and referenced on sensitive operations +- [ ] Tags have descriptions when your standard requires them +``` + +Promote recurring AI findings into new rule entries when they can be expressed as assertions, the same pattern as style guide enforcement. + +## Find workflow gaps with AI + +[Use AI as a usability tester](https://redocly.com/learn/ai-for-docs/ai-usability-testing) 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. + +```markdown {% process=false %} +You are auditing documentation coverage for integrators. + +Inputs: +- Table of contents or sitemap (headings and URLs only) +- OpenAPI table of contents (tags and operation summaries) + +For each workflow below, list: +1. Steps documented with links +2. Steps missing or only implied +3. Assumed knowledge not defined elsewhere + +Workflows: +- New developer: account, API key, first authenticated request +- Webhook consumer: subscribe, verify signature, retry policy +- Rate limit handling: detect 429, backoff, resume + +Do not invent endpoints. Cite missing sections by heading or "missing". +``` + +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. + +## Before and after: pagination tutorial + +Before: a tutorial jumps from "list users" to "handle large datasets" without stating default page size, cursor field names, or end-of-list behavior. + +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. + +AI helps you notice the jump; lint might still pass because each endpoint page is individually valid. Humans choose the narrative order. + +## Runtime gaps with Respect + +Some gaps appear only when code ships: response fields differ from the schema, status codes change, or sandbox behavior diverges from production. [Respect](https://redocly.com/respect) and [Respect use cases](https://redocly.com/docs/respect/use-cases) include running Arazzo workflows on a schedule against live endpoints and alerting when results diverge from the spec you publish. + +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. [API contract testing with Arazzo](https://redocly.com/blog/api-contract-testing-arazzo) explains how multi-step flows fit CI and monitoring. + +## Pair coverage review with editorial standards + +[Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-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. + +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. + +## Best practices + +Run lint on every spec change; run AI workflow audits on navigation or tutorial edits. + +Keep a single backlog with labels structural, workflow, and runtime so writers know which tool owns the fix. + +Link from inventory rows in your CMS to OpenAPI operationIds when possible so gaps stay traceable. + +Re-run the same AI prompt after fixes; diff the missing lists to prove progress. + +## What each layer cannot see + +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. + +None of the three replaces product managers who decide which workflows deserve first-class guides. + +## The balance + +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. + +## Learn more + +To enforce required fields and examples in OpenAPI at scale, start with [Explore Redocly CLI](https://redocly.com/docs/cli/) and [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules), then extend coverage with [configurable rules](https://redocly.com/docs/cli/rules/configurable-rules). diff --git a/learn/ai-for-docs/ai-generate-first-drafts-from-openapi.md b/learn/ai-for-docs/ai-generate-first-drafts-from-openapi.md new file mode 100644 index 00000000..7a80abf3 --- /dev/null +++ b/learn/ai-for-docs/ai-generate-first-drafts-from-openapi.md @@ -0,0 +1,101 @@ +--- +seo: + title: Use AI to generate first drafts from your OpenAPI spec + description: How to prompt an LLM from OpenAPI for summaries and examples, what humans must still verify, and how Redoc renders the page while Redocly CLI decorators and lint keep the spec trustworthy. +--- + +# Use AI to generate first drafts from your OpenAPI spec + +The spec already names operations, parameters, and schemas. Readers still need prose that explains tasks, highlights required fields, and shows realistic examples. A large language model can draft that layer quickly, but it will invent details if you let it. Keep the spec authoritative, render with [Redoc CE documentation](https://redocly.com/docs/redoc), and run [Explore Redocly CLI](https://redocly.com/docs/cli/) with [API standards and governance](https://redocly.com/docs/cli/api-standards) so text and schema stay aligned before you ship. + +This article covers what belongs in a first pass, what humans must verify, and how Redoc plus CLI decorators publish enriched output without silently rewriting the YAML people review in Git. + +## What belongs in a first draft from OpenAPI + +Readers search for a task before they read raw `paths`. A useful first pass adds a short overview per important operation, a parameter table that marks required fields, request and response examples grounded in schemas, and links to related errors or follow-on calls. Cover auth, pagination, idempotency, and limits once, then link from operations that depend on them. + +Thin specs yield thin drafts. When descriptions are empty, paste release notes or FAQs beside the prompt and label them non-authoritative so nobody treats model text as a spec edit by accident. + +## What models handle well versus what humans still own + +Models compress structure into readable prose fast. They handle `oneOf` and discriminator shapes, summarize enums without raw JSON dumps, and draft curl-shaped examples when you name your stack. + +Humans still own factual accuracy, legal wording, performance claims, and private routing rules the file never recorded. You own brand tone and which operations belong in public docs. If a field is deprecated in chat but not in OpenAPI, paste that fact next to the prompt or fix the spec first. + +## How to prompt AI with your OpenAPI file + +### Context block template + +Paste something shaped like this before the YAML or JSON: + +```markdown {% process=false %} +You are drafting human-facing API reference prose from OpenAPI 3.1. + +Audience: +- Backend engineers integrating for the first time this week. + +Rules: +- Do not invent endpoints, fields, status codes, or headers that are not in the pasted spec. +- When the spec is ambiguous, write "unspecified in OpenAPI" instead of guessing. +- Prefer short paragraphs and Markdown tables for parameters. + +Deliverables per listed operationId: +1. A two to four sentence overview of what the call does in product terms. +2. A Markdown table: name, in, required, type, description (copy descriptions from the spec when present). +3. One request example and one success response example using realistic but fake data. +4. Links (relative Markdown) to auth and error reference pages if those paths exist in the same repo outline I paste below. +``` + +Paste the same OpenAPI slice readers will see, bundled if your repo splits files across folders. If navigation lives outside the spec, paste that outline too so cross-links in the draft match your sidebar. + +### Review checklist for the model + +Cover error bodies, security per operation, and any `examples` fields so JSON matches declared types. Require a short assumptions list anywhere the model went beyond the file. + +## How Redoc turns the spec into a reference site + +[Redoc CE documentation](https://redocly.com/docs/redoc) describes the three-panel layout readers expect: navigation, operation detail, nested schemas. Follow the [Redoc CE quickstart](https://redocly.com/docs/redoc/quickstart) or run the [build-docs command](https://redocly.com/docs/cli/commands/build-docs) through [Explore Redocly CLI](https://redocly.com/docs/cli/) so CI emits static HTML from the same file the model read. + +When prose overclaims behavior, comparing the draft to the rendered schema panel surfaces the gap quickly. + +## Where Redocly CLI decorators and lint fit + +[Decorators](https://redocly.com/docs/cli/decorators) apply repeatable build-time edits: filter internal operations, add examples, or tune descriptions for publication while engineering keeps a stricter root file, as described under [API standards and governance](https://redocly.com/docs/cli/api-standards). That split helps when AI suggests friendlier copy you are not ready to merge into canonical YAML. + +After you change the OpenAPI itself, run [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) through the [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) so examples still validate and required fields stay consistent. + +## What AI cannot guarantee + +Models cannot certify that examples hit your staging stack, that quotas match production, or that legal text is correct per region. Pasting live tokens to chase realism leaks secrets. + +Use AI to shorten reading time. Use reviewers plus automated lint to certify what readers may rely on. + +## Best practices + +1. Paste bundled OpenAPI or the exact slice you publish so paths and component names match what Redoc will render. +2. Ask the model to output a change list of assumptions separate from spec-backed text. +3. Put decorator-driven publication tweaks in `redocly.yaml` so they are reviewable like code. +4. Run lint on the spec after every merge that touches examples or descriptions. + +## What this approach cannot replace + +This approach cannot replace ship-team review, legal review of commitments, or research on the tasks readers perform. It speeds structure-to-HTML work; it does not transfer ownership of API behavior. + +## How the pieces fit together + +```mermaid +graph LR + O[OpenAPI source] --> L[LLM prose draft] + L --> H[Human edits spec or text] + H --> C[Redocly CLI lint and decorate] + C --> B[build-docs output] + B --> P[Redoc layout for readers] +``` + +Structure becomes prose, then CLI tooling ties published pages back to the same rules on every build. + +## Learn more + +Start from [Redoc CE documentation](https://redocly.com/docs/redoc) and the [Redoc CE quickstart](https://redocly.com/docs/redoc/quickstart) when you want OpenAPI to become a navigable reference layout. + +Add [Explore Redocly CLI](https://redocly.com/docs/cli/), the [build-docs command](https://redocly.com/docs/cli/commands/build-docs), and [decorators](https://redocly.com/docs/cli/decorators) when you want lintable specs, repeatable enrichments, and static HTML in one pipeline. diff --git a/learn/ai-for-docs/ai-help-developers-find-understand-apis.md b/learn/ai-for-docs/ai-help-developers-find-understand-apis.md new file mode 100644 index 00000000..4834bf40 --- /dev/null +++ b/learn/ai-for-docs/ai-help-developers-find-understand-apis.md @@ -0,0 +1,102 @@ +--- +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. +--- + +# Use AI to help developers find and understand your APIs faster + +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 [Use AI to test your documentation's usability](https://redocly.com/learn/ai-for-docs/ai-usability-testing) complements this work by showing where linear docs still fail. + +## From linear reading to task-shaped questions + +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 (`Get an access token`, `List webhooks`) rather than around internal team names. + +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. + +## External developers and Revel + +[Revel](https://redocly.com/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 [Search configuration](https://redocly.com/docs/realm/config/search) and [AI assistant configuration](https://redocly.com/docs/realm/config/ai-assistant) when your project uses those Realm options. + +External readers care about stability promises and copy-paste examples. Keep changelog links adjacent to breaking changes. + +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. + +## Internal teams and Reef + +Employees need a different view: ownership, scorecards, and which API is canonical when duplicates exist. [Reef](https://redocly.com/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. + +## Doc structure models can navigate + +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 [optimizations for LLMs](https://redocly.com/blog/optimizations-to-make-to-your-docs-for-llms) article lists practical edits that also help human skimmers. + +### Page template you can reuse + +```markdown {% process=false %} +# Task title (verb + object) + +Prerequisites: links to auth and environment setup. + +## Steps +Numbered calls with request and response samples. + +## Errors +Table mapping codes to causes and fixes. + +## Related +Links to adjacent tasks only. +``` + +## llms.txt and assistant-ready surfaces + +Publish a machine-readable index such as [llms.txt](https://redocly.com/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. + +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 [How AI fits into modern API documentation](https://redocly.com/learn/ai-for-docs/ai-modern-api-docs) so writers remember that assistants consume the same pages humans read. + +### Retrieval-friendly snippets + +Keep code samples copy-paste ready with real hostnames for sandbox, not placeholders like `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. + +```mermaid +graph TD + Q[Developer question] --> R{Audience} + R -->|External| V[Revel docs search] + R -->|Internal| F[Reef catalog] + V --> A[Answer fragment] + F --> A + A --> N[Next task link] +``` + +The diagram is simple on purpose: every answer should point to the next step. + +## Best practices + +Test five onboarding tasks monthly with only public docs, as described in the usability article. + +Mirror task titles between internal and external docs when the workflow is the same. + +Surface auth and environment setup on every quickstart, not only on a distant overview. + +Measure time-to-first-successful-call, not page views alone. + +Record which pages assistants cite when answers are wrong, then fix headings on those pages first. + +Keep internal Reef entries linked from external Revel pages when partners should not see internal routes. + +Review search queries quarterly and add missing task pages when the same question repeats. + +Publish a short getting-started path that links three tasks in order so both humans and assistants follow the same sequence. + +## What assistants cannot infer + +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. + +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. + +## Summary + +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. + +## Learn more + +[Revel](https://redocly.com/revel) is the external developer portal where structured quickstarts, search, and assistant features help integrators finish tasks without reading the entire site. diff --git a/learn/ai-for-docs/ai-review-api-design-gaps-inconsistencies.md b/learn/ai-for-docs/ai-review-api-design-gaps-inconsistencies.md new file mode 100644 index 00000000..bd454ef1 --- /dev/null +++ b/learn/ai-for-docs/ai-review-api-design-gaps-inconsistencies.md @@ -0,0 +1,126 @@ +--- +seo: + title: Use AI to review API design for gaps and inconsistencies + description: Share OpenAPI or design notes with a model to find missing workflows and inconsistent patterns, then validate changes with Redocly CLI lint before merge. +--- + +# Use AI to review API design for gaps and inconsistencies + +You can ask a model to read OpenAPI or design notes before handlers ship, then gate changes with Redocly CLI lint in the same pull request. The learn article [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews) covers the wider review pattern; here the focus stays on API shape, workflows, and naming drift while lint covers spec compliance and governance. + +## When design review belongs before implementation + +Early review is cheaper than retrofitting routes, error models, and pagination after clients exist. A model can scan many paths at once and compare them against the story you tell about actors, states, and edge cases. It does not replace your product judgment, but it gives you a second reader that is patient with long YAML. + +## Inputs that make the review specific + +Paste enough domain context that a newcomer could role-play your user. List primary actors, the workflows they care about, and the invariants you already know, for example holds on inventory or partial refunds. + +Add either a full OpenAPI file or a curated excerpt. If the file is huge, scope the excerpt to the surface you are changing and link to the rest in prose. The goal is signal density, not token volume for its own sake. + +### Domain context block you can paste + +```markdown {% process=false %} +Context: We run a small logistics network for cold freight. +Actors: shippers, carriers, warehouse staff. +Workflows: booking a lane, changing pickup windows, recording temperature excursions. + +Review this OpenAPI excerpt for gaps and inconsistencies: +[paste paths, schemas, or notes] +``` + +## Prompt skeleton for gaps and inconsistencies + +Keep the ask structured so the answer is easy to triage. You can start from this outline and tune nouns to your domain. + +```markdown {% process=false %} +You are reviewing an API design for [one sentence domain]. + +Please list: +1. Missing CRUD or state transitions implied by the domain but absent from paths. +2. Incomplete workflows where a user would reach a dead end. +3. Naming inconsistencies across resources, parameters, and schema fields. +4. Edge cases we should model explicitly, including error shapes. +5. Authentication or authorization gaps relative to the described roles. + +[paste OpenAPI or notes] +``` + +## Signals the model often finds + +Across teams, the same review surfaces a short set of themes. Missing companion operations appear when create exists without read or cancel. URL style drifts between `/resource/{id}` and query variants for the same concept. Domain gaps show up when a user can start a workflow but cannot observe status or reverse an action. Security gaps cluster around admin-only routes that lack explicit scopes or consistent error contracts. + +Treat the list as a prioritized backlog, not a verdict. Some suggestions will not fit your roadmap or risk appetite. + +## Thin before and after on paths and verbs + +Before: + +```yaml {% process=false %} +paths: + /shipments: + post: + summary: Create shipment +``` + +After: + +```yaml {% process=false %} +paths: + /shipments: + post: + summary: Create shipment + get: + summary: List shipments for the authenticated account + /shipments/{shipmentId}: + get: + summary: Retrieve a single shipment + patch: + summary: Update allowed fields on a draft shipment +``` + +The second sketch does not prove correctness, but it shows how a gap review nudges you toward coherent CRUD before you wire handlers. + +```mermaid +graph LR + A[Domain context plus OpenAPI] --> B[Model review] + B --> C[Human edits] + C --> D[redocly lint] + D --> E[Pull request] +``` + +The loop is intentionally short. You want feedback while the design is still cheap to edit. + +## Run lint after you merge suggestions + +When you accept changes, run the [lint command](https://redocly.com/docs/cli/commands/lint) against the same file the model saw. Lint applies preprocessors and rules, reports problems in OpenAPI and related formats, and does not run decorators, which keeps this step focused on spec shape. + +In continuous integration, you can point the same command at pull requests so every spec edit repeats the same checks your authors run locally. That repetition matters because models sometimes suggest keywords or vendor extensions your ruleset has not whitelisted yet, and lint catches those mismatches early. + +If you have no local config yet, the command defaults to the [recommended ruleset](https://redocly.com/docs/cli/rules/recommended). You can extend coverage with [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) and [configurable rules](https://redocly.com/docs/cli/rules/configurable-rules) as your standards mature. + +## Align checks with governance + +Organizations that treat OpenAPI as law usually centralize how rules are authored and shared. The [API standards and governance](https://redocly.com/docs/cli/api-standards) page describes how CLI and hosted flows can reuse the same configuration so developers see the same violations locally and in automation. For first-time setup, the [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules) walks through a practical baseline you can grow over time. + +## Best practices + +Ship context, not vibes. Short checklists beat long prose in the prompt. + +Review one theme at a time when the file is large, for example naming first, then errors, then pagination. + +Log model findings as tickets with spec anchors so humans can accept or reject with traceability. + +Combine model passes with deterministic tools so subjective completeness meets objective gates, which mirrors the guidance in [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews). + +## Limits of this pairing + +Models do not know your private roadmap, real traffic mixes, or regulatory commitments unless you state them. They can hallucinate fields or routes if you ask for rewrites without grounding them in your repository facts. Lint cannot judge whether a workflow is fair to users, only whether the document obeys configured rules. + +## Summary + +Use a structured prompt plus domain context to surface gaps early, then let Redocly CLI enforce the rules your team already agreed to. Keep humans in the loop for trade-offs, and treat automation as a safety net rather than a substitute for product sense. + +## Learn more + +When you are ready to wire the deterministic side of the loop, start with [Explore Redocly CLI](https://redocly.com/docs/cli/) for installation, first commands, and how lint fits alongside bundling and preview workflows described in the broader [rulesets](https://redocly.com/docs/cli/rules) documentation. diff --git a/learn/ai-for-docs/ai-review-code-examples-completeness-accuracy.md b/learn/ai-for-docs/ai-review-code-examples-completeness-accuracy.md new file mode 100644 index 00000000..14886cfe --- /dev/null +++ b/learn/ai-for-docs/ai-review-code-examples-completeness-accuracy.md @@ -0,0 +1,132 @@ +--- +seo: + title: Use AI to review code examples for completeness and accuracy + description: How to prompt AI to audit request samples against your OpenAPI spec, which gaps models catch, and how Redocly code sample generation, mock server, and CLI lint give you a runnable baseline. +--- + +# Use AI to review code examples for completeness and accuracy + +Developers copy the curl block or SDK snippet before they read the prose. When auth headers are missing, optional query params disappear, or the JSON shape no longer matches the schema, integrations fail in silence until someone files a ticket. A large language model can compare pasted examples to your OpenAPI slice and flag pattern gaps fast. You still need deterministic checks so the samples readers copy match what your spec and mock server actually return. + +This article covers the failures that show up most often, how to prompt for a structured review, and how [Redoc CE documentation](https://redocly.com/docs/redoc), [generate code samples automatically](https://redocly.com/docs/api-reference-docs/guides/generate-code-samples), the [configure mock server](https://redocly.com/docs/realm/content/api-docs/configure-mock-server) flow, and the [lint command](https://redocly.com/docs/cli/commands/lint) through [Explore Redocly CLI](https://redocly.com/docs/cli/) close the loop after AI suggests fixes. + +## Common ways code examples drift from the spec + +Pseudocode that looks runnable is the usual culprit. Tutorials show `fetch('/users')` without the base URL your `servers` block defines, or they omit the `Content-Type` header when the operation expects JSON. + +Auth gaps appear when global `security` applies but the snippet is anonymous. Multi-scheme specs make this worse: generated samples often include only the first scheme unless you document the others beside the example. + +Schema drift shows up as field names from an old release, numbers sent as strings, or nested objects flattened. Optional parameters vanish from copy-paste-friendly snippets even when the operation lists them, which hides pagination and filter behavior new integrators need. + +Outdated SDK syntax is harder for linters alone. A model that knows your pinned library version can flag deprecated method names if you state the version in the prompt. + +## What to paste beside the OpenAPI slice + +Give the model the same operation definitions readers see, including `requestBody`, `parameters`, `security`, and any `examples` or [x-codeSamples extension](https://redocly.com/docs/api-reference-docs/specification-extensions/x-code-samples) blocks. Paste tutorial snippets from Markdown or your docs repo as separate labeled files so the model knows which text is canonical. + +Add a short stack note: language, HTTP client, whether examples should use the first `servers` URL or a named environment. List environment variable placeholders you expect, such as `API_KEY` or `BASE_URL`, so the review can flag hard-coded secrets or missing substitution. + +State which samples are hand-written versus generated. Custom `x-codeSamples` override auto-generated tabs for that language, so reviewers should not treat generated curl as the source of truth when a custom block exists. + +## Prompt template for an example review + +Use a checklist-shaped prompt so output is actionable in a PR comment. + +```markdown {% process=false %} +You are reviewing API code examples against OpenAPI 3.1. + +Stack: Node 20, undici fetch, bearer token auth. + +Rules: +- Flag any field, header, path, or status code not supported by the pasted spec. +- Flag missing required parameters, auth, or content types. +- Flag JSON that would fail validation against the declared schema. +- Do not rewrite examples unless asked; output a table of issues with severity. + +Deliverables: +1. Table: location, issue, spec reference, suggested fix. +2. List of operations with no example at all. +3. Assumptions you made about base URL or auth. +``` + +Ask for severity so authors can fix blockers before polish. Require an explicit assumptions section anywhere the model inferred behavior the file does not state. + +### Review checklist for humans after the model runs + +Confirm error responses for auth failures are demonstrated when your security section requires them. Check that pagination parameters appear in at least one list example when the schema supports them. Compare Content-Type and Accept headers to what the operation declares. + +Run the same checklist on release notes when they include one-off curl blocks outside the spec repo. + +## Before and after a single operation + +Before, a hand-written curl omits auth and sends the wrong field name: + +```bash +curl -X POST https://api.example.com/v1/events \ + -H "Content-Type: application/json" \ + -d '{"title":"Pool party","when":"2026-06-01"}' +``` + +After alignment with the spec, the snippet names the bearer scheme, uses `name` and `startDate`, and points readers to the documented server URL: + +```bash +curl -X POST "https://api.example.com/v1/events" \ + -H "Authorization: Bearer $ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name":"Pool party","startDate":"2026-06-01"}' +``` + +AI can produce the gap table that motivates this edit. Your reviewers still approve whether the example should show optional fields or a minimal payload. + +## Build a deterministic baseline readers can trust + +[Generate code samples automatically](https://redocly.com/docs/api-reference-docs/guides/generate-code-samples) creates request tabs from the same OpenAPI fields your lint rules guard. Configure languages in your API reference docs settings or `redocly.yaml` so curl, JavaScript, or Python tabs stay in sync when parameters change. Remember that auto-generated tabs are not available in Redoc CE alone; CE still renders samples you embed with [x-codeSamples extension](https://redocly.com/docs/api-reference-docs/specification-extensions/x-code-samples). + +The [configure mock server](https://redocly.com/docs/realm/content/api-docs/configure-mock-server) option serves example responses without a live backend. Use `strictExamples` when you want responses to match documented JSON exactly, or relax it when you want request values echoed for interactive demos. Send the same request through [Replay API explorer](https://redocly.com/docs/end-user/test-apis-replay) after you change an example to see whether the mock returns the status and body your text promises. + +Treat generated curl and mock responses as the baseline. Ask AI to diff hand-written tutorials against that baseline instead of against memory. + +## Where Redocly CLI lint fits + +Run the [lint command](https://redocly.com/docs/cli/commands/lint) on every spec change that touches examples. [built-in rules](https://redocly.com/docs/cli/rules/built-in-rules) catch structural problems, such as invalid references or missing operation metadata, while you can extend coverage through the [guide to configuring a ruleset](https://redocly.com/docs/cli/guides/configure-rules). + +Lint proves the `examples` payload matches declared types. It does not know whether your Python import path exists on PyPI this week. Keep AI review for readability and library idioms; keep CLI lint for contract truth on the OpenAPI file itself. + +## What AI cannot verify + +Models do not execute code against your staging stack unless you wire a separate agent with credentials, which most doc teams avoid in review bots. They cannot confirm rate limits, regional endpoints, or private headers you never added to the spec. + +Pasting production tokens into a chat to test realism leaks secrets. Use placeholder env vars in examples and mock server calls instead. + +## Best practices + +1. Paste bundled OpenAPI for the operations your tutorial covers so component schema names match lint output. +2. Keep hand-written samples in Git beside the spec or in `x-codeSamples` so diffs stay reviewable. +3. Compare AI findings to generated curl and one mock server response before you merge doc changes. +4. Re-run [Explore Redocly CLI](https://redocly.com/docs/cli/) lint after every edit to `examples` or sample extensions. + +## What this approach cannot replace + +This approach cannot replace SDK maintainer review, security review of credential handling, or user research on which tasks need copy-paste samples versus conceptual explanation. AI accelerates gap detection; mock server and lint prove the contract layer. + +## How the pieces fit together + +```mermaid +graph TD + S[OpenAPI plus pasted samples] --> A[AI gap report] + A --> H[Author fixes examples] + H --> L[Redocly CLI lint] + H --> G[Generated code samples] + H --> M[Mock server or Replay] + L --> P[Published reference docs] + G --> P + M --> P +``` + +AI surfaces mismatches, then lint, generated samples, and mock responses keep published tabs aligned with the spec. + +## Learn more + +Start from [Redoc CE documentation](https://redocly.com/docs/redoc) when you want OpenAPI-backed reference pages that display the samples you certify in Git. + +Add [Explore Redocly CLI](https://redocly.com/docs/cli/), the [lint command](https://redocly.com/docs/cli/commands/lint), and [generate code samples automatically](https://redocly.com/docs/api-reference-docs/guides/generate-code-samples) when you want lintable specs, generated request tabs, and mock server checks in one pipeline. diff --git a/learn/ai-for-docs/ai-review-docs-navigation-structure.md b/learn/ai-for-docs/ai-review-docs-navigation-structure.md new file mode 100644 index 00000000..a7c1e413 --- /dev/null +++ b/learn/ai-for-docs/ai-review-docs-navigation-structure.md @@ -0,0 +1,131 @@ +--- +seo: + title: Use AI to review your docs navigation structure + description: How to paste a sitemap or folder tree for AI review, which navigation mistakes models flag for new readers, and how Reunite visual pull request review validates a restructure before publish. +--- + +# Use AI to review your docs navigation structure + +Readers decide whether your API is approachable before they read a single endpoint description. They scan the sidebar, search for authentication, and bail when errors live three levels deep under a label that sounds unrelated. A large language model cannot replace analytics, but it can read your folder tree or `sidebars.yaml` outline and flag patterns that confuse first-time integrators. + +This article shows what to paste into a navigation review, the problems that show up repeatedly, a before-and-after tree you can adapt from [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews), and how to validate the restructure in [Reunite](https://redocly.com/reunite) before you merge. + +## What to share with the model + +Paste the structure readers actually see, not an internal wiki map. That usually means a folder tree from your docs repo, the ordered list from [Sidebars configuration options](https://redocly.com/docs/realm/navigation/sidebars), or an export of your published sidebar labels. + +Add a short persona block: who arrives cold this week, what they need to accomplish in the first session, and which pages you consider prerequisites. Without tasks, the model defaults to generic "logical grouping" advice. + +Note whether navigation is file-driven or explicit. [Navigation in Realm](https://redocly.com/docs/realm/navigation/navigation) explains that missing `sidebars.yaml` often means order follows the file tree, which may not match how you want newcomers to read. + +## Prompt template for a navigation review + +Keep the prompt checklist-shaped so output is actionable in a restructuring PR. + +```markdown {% process=false %} +You are reviewing documentation navigation for a first-time API integrator. + +Tasks they must complete in order: +1. Create an account and obtain API credentials +2. Authenticate and make a first successful request +3. Handle common errors and rate limits +4. Subscribe to webhooks for order updates + +Review the pasted folder tree and answer: +1. Which tasks are hard to discover from the sidebar alone? +2. Which sections are too deep (more than two clicks from a sensible entry point)? +3. Which topics are split across unrelated top-level groups? +4. Propose a revised tree with one-line justification per move. +5. List assumptions about reader skill level. +``` + +Ask for a table of moves rather than a full rewrite of every filename so authors can apply changes incrementally. + +## Problems AI often flags for new readers + +Authentication buried under advanced guides is the classic miss. Integrators expect auth beside getting started, not under a catch-all reference folder they open only after a failed curl. + +Error and rate-limit content separated from the operations that trigger those responses forces readers to context-switch. Models often suggest moving error catalogs adjacent to API reference or linking them prominently from getting started. + +Examples orphaned at the root while conceptual guides sit elsewhere make tutorials feel optional when they are the real on-ramp. Webhooks promoted to top level without a prerequisite auth page strand readers who land from search. + +Orphan pages with no parent group show up when teams add files faster than they update [Sidebars configuration options](https://redocly.com/docs/realm/navigation/sidebars). Ask the model to list files that appear disconnected from any stated task flow. + +## Before and after a flat top-level layout + +The learn article on reviews uses a flat tree where foundational topics compete with reference material: + +``` +docs/ +├── getting-started/ +├── api-reference/ +├── webhooks/ +├── authentication/ +├── rate-limiting/ +├── errors/ +└── examples/ +``` + +A tighter shape for the same content groups onboarding, nests errors with reference, and tuck examples under guides: + +``` +docs/ +├── getting-started/ +│ ├── authentication.md +│ ├── first-api-call.md +│ └── rate-limits.md +├── api-reference/ +│ ├── endpoints/ +│ └── errors.md +├── guides/ +│ ├── webhooks.md +│ └── examples/ +└── advanced/ +``` + +The moves are explainable in reader terms. Authentication and rate limits belong with first steps. Errors are reference material readers consult from operation pages. Examples are guides, not a peer of the API catalog. + +Your product names differ, but the pattern repeats: pull prerequisites up, push deep reference down, and reduce top-level siblings. + +## Validate the restructure in Reunite before publish + +AI proposes moves. Humans still need to see rendered navigation with real labels and cross-links. Edit `sidebars.yaml` or move files in the [use the editor](https://redocly.com/docs/realm/reunite/project/use-editor) flow, open a pull request, and ask reviewers to use [review a pull request in Reunite](https://redocly.com/docs/realm/reunite/project/pull-request/review-pull-request). + +The Review tab opens in Visual view by default, showing rendered pages before and after your changes. That is the right place to confirm a moved auth page still reads well in context and that examples under guides did not break sidebar depth. + +Toggle to Code when you need to verify `sidebars.yaml` ordering line by line. Filter the file tree on large PRs so reviewers can focus on navigation files first. + +Treat the visual diff as the acceptance test for the AI plan. If the sidebar still hides credentials behind three clicks in the preview, reject the merge even when the folder tree looks tidy in Git. + +## What AI cannot infer about your audience + +Models do not see search console data, support ticket tags, or which pages your sales team demos most. They may over-weight alphabetical order or symmetry when your readers arrive from one high-intent landing page. + +They also cannot know internal politics about which product name must appear in a top-level label. Use AI for reader-task fit; use stakeholders for naming commitments. + +## Best practices + +1. Paste the same sidebar order production uses, including hidden or draft sections you plan to publish soon. +2. List five to eight first-week tasks explicitly so the model judges discoverability against work, not aesthetics. +3. Apply navigation changes in a dedicated PR with only IA edits when possible so visual review stays focused. +4. Re-run the prompt after major feature launches because new guides often land as orphan files. + +## What this approach cannot replace + +This approach cannot replace quantitative path analysis, card-sort studies with real users, or accessibility review of navigation landmarks. It speeds structural critique before you invest in a full rework. + +## How the pieces fit together + +```mermaid +graph LR + T[Folder tree or sidebars.yaml] --> A[AI navigation report] + A --> E[Edit structure in Reunite] + E --> V[Visual PR review] + V --> M[Merge and deploy] +``` + +The model narrows which moves are worth trying; Reunite visual review proves the sidebar works for humans. + +## Learn more + +When you want Git-backed editing, pull request review, and side-by-side visual diffs on navigation changes, start with [Reunite](https://redocly.com/reunite) and the [Reunite documentation](https://redocly.com/docs/realm/reunite/reunite) hub for editor and review workflows. diff --git a/learn/ai-for-docs/ai-reviews.md b/learn/ai-for-docs/ai-reviews.md index 2f296762..ec4b2316 100644 --- a/learn/ai-for-docs/ai-reviews.md +++ b/learn/ai-for-docs/ai-reviews.md @@ -30,7 +30,7 @@ Instead of: > "Use active voice. Passive voice makes documentation harder to read and can obscure who is responsible for actions. Technical documentation should clearly indicate the actor performing each action..." Use: -```markdown +```markdown {% process=false %} - [ ] Active voice (e.g., "The API returns..." not "Data is returned...") - [ ] Present tense for current features - [ ] Use "you" to address the reader @@ -69,7 +69,7 @@ Before writing any code, share your API design (OpenAPI description, schema draf Generic reviews aren't helpful. You need to give AI enough context about your domain: -```markdown +```markdown {% process=false %} Context: We're building a library management system. Users are librarians and patrons. Key workflows: checking out books, managing holds, handling fines. @@ -89,7 +89,7 @@ I've used this successfully to find **entire sections of forgotten domain areas* ### Example prompt -```markdown +```markdown {% process=false %} You are reviewing an API design for [domain description]. Please identify: @@ -205,7 +205,7 @@ Then ask: Does the structure and content support easy task completion? What coul ### Example prompt -```markdown +```markdown {% process=false %} Users need to accomplish these tasks: 1. Authenticate with the API 2. Create a new user diff --git a/learn/ai-for-docs/ai-usability-testing.md b/learn/ai-for-docs/ai-usability-testing.md index 56160577..5c563dd4 100644 --- a/learn/ai-for-docs/ai-usability-testing.md +++ b/learn/ai-for-docs/ai-usability-testing.md @@ -193,7 +193,7 @@ When you ship a new API version or feature: ### Example automation -```markdown +```markdown {% process=false %} On every docs PR: 1. Run AI through 5 critical user tasks 2. Flag tasks where AI asks clarifying questions (doc gaps) @@ -319,7 +319,7 @@ Ask AI to complete it using only your documentation. Watch where it struggles. ### Document the pattern Create a template for AI usability tests: -```markdown +```markdown {% process=false %} Task: [Specific, completable goal] Documentation provided: [Links or content] Success criteria: [How you know it worked] diff --git a/learn/ai-for-docs/sidebars.yaml b/learn/ai-for-docs/sidebars.yaml index 988564de..7dd3c889 100644 --- a/learn/ai-for-docs/sidebars.yaml +++ b/learn/ai-for-docs/sidebars.yaml @@ -1,3 +1,36 @@ - page: ai-modern-api-docs.md + label: How AI fits into modern API documentation - page: ai-reviews.md -- page: ai-usability-testing.md \ No newline at end of file + label: Use AI to accelerate and improve reviews +- page: ai-auth-authorization-patterns.md + label: Use AI to check authentication and authorization patterns +- page: ai-review-api-design-gaps-inconsistencies.md + label: Use AI to review API design for gaps and inconsistencies +- page: ai-api-design-backward-compatibility-risks.md + label: Use AI to review API design for backward compatibility risks +- page: ai-generate-first-drafts-from-openapi.md + label: Use AI to generate first drafts from your OpenAPI spec +- page: ai-enforce-tone-style-consistency-across-docs.md + label: Use AI to enforce tone and style consistency across docs +- page: ai-review-code-examples-completeness-accuracy.md + label: Use AI to review code examples for completeness and accuracy +- page: ai-automate-documentation-reviews-pr-workflow.md + label: Use AI to automate documentation reviews in your PR workflow +- page: ai-review-docs-navigation-structure.md + label: Use AI to review your docs navigation structure +- page: ai-enforce-api-style-guide-at-scale.md + label: Use AI to enforce your API style guide at scale +- page: ai-find-gaps-documentation-coverage.md + label: Use AI to find gaps in your documentation coverage +- page: ai-detect-drift-docs-live-api.md + label: Use AI to detect drift between your docs and your live API +- page: ai-find-duplicate-underused-apis.md + label: Use AI to find duplicate and underused APIs in your codebase +- page: ai-build-searchable-api-catalog.md + 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-check-terminology-consistency-across-docs.md + label: Use AI to check terminology consistency across your docs +- page: ai-usability-testing.md + label: Use AI as a usability tester diff --git a/pages/learning-center/cards.ts b/pages/learning-center/cards.ts index 80b0c2d7..15063b3f 100644 --- a/pages/learning-center/cards.ts +++ b/pages/learning-center/cards.ts @@ -142,6 +142,66 @@ export const cards = [ items: [ { title: 'AI for Modern Documentation', link: '/learn/ai-for-docs/ai-modern-api-docs' }, { title: 'AI for Reviews', link: '/learn/ai-for-docs/ai-reviews' }, + { + title: 'AI for authentication and authorization patterns', + link: '/learn/ai-for-docs/ai-auth-authorization-patterns', + }, + { + title: 'Use AI to review API design for gaps and inconsistencies', + link: '/learn/ai-for-docs/ai-review-api-design-gaps-inconsistencies', + }, + { + title: 'Use AI to review API design for backward compatibility risks', + link: '/learn/ai-for-docs/ai-api-design-backward-compatibility-risks', + }, + { + title: 'Use AI to generate first drafts from your OpenAPI spec', + link: '/learn/ai-for-docs/ai-generate-first-drafts-from-openapi', + }, + { + title: 'Use AI to enforce tone and style consistency across docs', + link: '/learn/ai-for-docs/ai-enforce-tone-style-consistency-across-docs', + }, + { + title: 'Use AI to review code examples for completeness and accuracy', + link: '/learn/ai-for-docs/ai-review-code-examples-completeness-accuracy', + }, + { + title: 'Use AI to automate documentation reviews in your PR workflow', + link: '/learn/ai-for-docs/ai-automate-documentation-reviews-pr-workflow', + }, + { + title: 'Use AI to review your docs navigation structure', + link: '/learn/ai-for-docs/ai-review-docs-navigation-structure', + }, + { + title: 'Use AI to enforce your API style guide at scale', + link: '/learn/ai-for-docs/ai-enforce-api-style-guide-at-scale', + }, + { + title: 'Use AI to find gaps in your documentation coverage', + link: '/learn/ai-for-docs/ai-find-gaps-documentation-coverage', + }, + { + title: 'Use AI to detect drift between your docs and your live API', + link: '/learn/ai-for-docs/ai-detect-drift-docs-live-api', + }, + { + title: 'Use AI to find duplicate and underused APIs in your codebase', + link: '/learn/ai-for-docs/ai-find-duplicate-underused-apis', + }, + { + title: 'Use AI to build a searchable API catalog for your team', + link: '/learn/ai-for-docs/ai-build-searchable-api-catalog', + }, + { + title: 'Use AI to help developers find and understand your APIs faster', + link: '/learn/ai-for-docs/ai-help-developers-find-understand-apis', + }, + { + title: 'Use AI to check terminology consistency across your docs', + link: '/learn/ai-for-docs/ai-check-terminology-consistency-across-docs', + }, { title: 'AI as a usability tester', link: '/learn/ai-for-docs/ai-usability-testing' }, ], }, From 3d45a12ab402fb8851f9f9ed4a79ba43ae4851c0 Mon Sep 17 00:00:00 2001 From: Justin Dunham Date: Wed, 20 May 2026 23:28:48 -0700 Subject: [PATCH 2/3] Tighten Learn AI for Docs card thumbnail and item list Replace the 1200x630 thumbnail SVG with a 378x112 cropped variant matching the other learning cards, and trim the visible items to five with an explicit "13 more topics" overflow indicator. --- pages/learning-center/cards.ts | 58 +------------------ .../images/ai-for-docs-thumbnail-cropped.svg | 52 +++++++++++++++++ .../images/ai-for-docs-thumbnail.svg | 52 +++++++---------- 3 files changed, 76 insertions(+), 86 deletions(-) create mode 100644 pages/learning-center/images/ai-for-docs-thumbnail-cropped.svg diff --git a/pages/learning-center/cards.ts b/pages/learning-center/cards.ts index 15063b3f..42ec9592 100644 --- a/pages/learning-center/cards.ts +++ b/pages/learning-center/cards.ts @@ -4,7 +4,7 @@ import yamlThumbnail from './images/yaml-thumbnail.svg'; import apiTestingThumbnail from './images/api-testing-thumbnail.svg'; import apiSecurityThumbnail from './images/api-security-thumbnail.svg'; import arazzoThumbnail from './images/arazzo-thumbnail.svg'; -import aiForDocsThumbnail from './images/ai-for-docs-thumbnail.svg'; +import aiForDocsThumbnail from './images/ai-for-docs-thumbnail-cropped.svg'; import getStartedThumbnail from './images/get-started-thumbnail.svg'; export const cards = [ @@ -137,7 +137,7 @@ export const cards = [ description: 'Learn how to use AI to improve your API documentation.', thumbnail: aiForDocsThumbnail, - moreItems: 'more topics coming soon', + moreItems: '13 more topics', landingPage: '/learn/ai-for-docs/ai-modern-api-docs', items: [ { title: 'AI for Modern Documentation', link: '/learn/ai-for-docs/ai-modern-api-docs' }, @@ -147,61 +147,9 @@ export const cards = [ link: '/learn/ai-for-docs/ai-auth-authorization-patterns', }, { - title: 'Use AI to review API design for gaps and inconsistencies', + title: 'AI for API design gaps and inconsistencies', link: '/learn/ai-for-docs/ai-review-api-design-gaps-inconsistencies', }, - { - title: 'Use AI to review API design for backward compatibility risks', - link: '/learn/ai-for-docs/ai-api-design-backward-compatibility-risks', - }, - { - title: 'Use AI to generate first drafts from your OpenAPI spec', - link: '/learn/ai-for-docs/ai-generate-first-drafts-from-openapi', - }, - { - title: 'Use AI to enforce tone and style consistency across docs', - link: '/learn/ai-for-docs/ai-enforce-tone-style-consistency-across-docs', - }, - { - title: 'Use AI to review code examples for completeness and accuracy', - link: '/learn/ai-for-docs/ai-review-code-examples-completeness-accuracy', - }, - { - title: 'Use AI to automate documentation reviews in your PR workflow', - link: '/learn/ai-for-docs/ai-automate-documentation-reviews-pr-workflow', - }, - { - title: 'Use AI to review your docs navigation structure', - link: '/learn/ai-for-docs/ai-review-docs-navigation-structure', - }, - { - title: 'Use AI to enforce your API style guide at scale', - link: '/learn/ai-for-docs/ai-enforce-api-style-guide-at-scale', - }, - { - title: 'Use AI to find gaps in your documentation coverage', - link: '/learn/ai-for-docs/ai-find-gaps-documentation-coverage', - }, - { - title: 'Use AI to detect drift between your docs and your live API', - link: '/learn/ai-for-docs/ai-detect-drift-docs-live-api', - }, - { - title: 'Use AI to find duplicate and underused APIs in your codebase', - link: '/learn/ai-for-docs/ai-find-duplicate-underused-apis', - }, - { - title: 'Use AI to build a searchable API catalog for your team', - link: '/learn/ai-for-docs/ai-build-searchable-api-catalog', - }, - { - title: 'Use AI to help developers find and understand your APIs faster', - link: '/learn/ai-for-docs/ai-help-developers-find-understand-apis', - }, - { - title: 'Use AI to check terminology consistency across your docs', - link: '/learn/ai-for-docs/ai-check-terminology-consistency-across-docs', - }, { title: 'AI as a usability tester', link: '/learn/ai-for-docs/ai-usability-testing' }, ], }, diff --git a/pages/learning-center/images/ai-for-docs-thumbnail-cropped.svg b/pages/learning-center/images/ai-for-docs-thumbnail-cropped.svg new file mode 100644 index 00000000..7d6b3454 --- /dev/null +++ b/pages/learning-center/images/ai-for-docs-thumbnail-cropped.svg @@ -0,0 +1,52 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + learning center + + + AI for Docs + + practical ways AI accelerates writing, editing, and review + + + diff --git a/pages/learning-center/images/ai-for-docs-thumbnail.svg b/pages/learning-center/images/ai-for-docs-thumbnail.svg index 3aa0a1ed..7ad686b6 100644 --- a/pages/learning-center/images/ai-for-docs-thumbnail.svg +++ b/pages/learning-center/images/ai-for-docs-thumbnail.svg @@ -1,4 +1,4 @@ - + @@ -10,53 +10,43 @@ - + + + + - - - - - - - - - - - - + + - - - - + + + - - - - learning center + + + learning center - - AI for Docs + letter-spacing="-0.4">AI for Docs - - practical ways AI accelerates writing, editing, and review - - + From bc28cae2e203b7f1692b68207e55d48d0991bc0e Mon Sep 17 00:00:00 2001 From: Adam Altman Date: Thu, 21 May 2026 14:10:48 -0500 Subject: [PATCH 3/3] chore: minor format changes Co-authored-by: Adam Altman --- learn/ai-for-docs/ai-enforce-api-style-guide-at-scale.md | 2 +- learn/ai-for-docs/ai-review-docs-navigation-structure.md | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/learn/ai-for-docs/ai-enforce-api-style-guide-at-scale.md b/learn/ai-for-docs/ai-enforce-api-style-guide-at-scale.md index 31518ea6..bc632e60 100644 --- a/learn/ai-for-docs/ai-enforce-api-style-guide-at-scale.md +++ b/learn/ai-for-docs/ai-enforce-api-style-guide-at-scale.md @@ -135,7 +135,7 @@ Use automation to make agreed standards unavoidable, workshops to reach agreemen ## The balance -A thin checklist, a reviewed redocly.yaml, and CI that runs the same rules on every service turns your style guide from shelfware into a default developers meet before merge. +A thin checklist, a reviewed `redocly.yaml`, and CI that runs the same rules on every service turns your style guide from shelfware into a default developers meet before merge. ## Learn more diff --git a/learn/ai-for-docs/ai-review-docs-navigation-structure.md b/learn/ai-for-docs/ai-review-docs-navigation-structure.md index a7c1e413..bdb341f3 100644 --- a/learn/ai-for-docs/ai-review-docs-navigation-structure.md +++ b/learn/ai-for-docs/ai-review-docs-navigation-structure.md @@ -55,7 +55,6 @@ Orphan pages with no parent group show up when teams add files faster than they The learn article on reviews uses a flat tree where foundational topics compete with reference material: -``` docs/ ├── getting-started/ ├── api-reference/ @@ -68,7 +67,6 @@ docs/ A tighter shape for the same content groups onboarding, nests errors with reference, and tuck examples under guides: -``` docs/ ├── getting-started/ │ ├── authentication.md