{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-learn/ai-for-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Learn","type":"markdown"},"seo":{"title":"Use AI to 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.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"use-ai-to-check-terminology-consistency-across-your-docs","__idx":0},"children":["Use AI to check terminology consistency across your docs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-reviews"},"children":["Use AI to accelerate and improve reviews"]},", but the checklist here focuses on language rather than API shape."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-the-same-concept-gets-three-names","__idx":1},"children":["How the same concept gets three names"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Terminology drift also shows up inside OpenAPI ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ai-audit-prompt-for-terminology","__idx":2},"children":["AI audit prompt for terminology"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste excerpts or file paths with a short domain note. Ask for conflicts, not rewrites, in the first pass."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"You are auditing documentation terminology for [product domain].\n\nCanonical terms we prefer:\n- organization (not tenant, not account) for B2B workspaces\n- member (not user) for people inside an organization\n\nScan the excerpts below and return a table:\n| term_used | preferred_term | file_or_section | severity |\n\nDo not rewrite prose yet.\n\n[paste markdown excerpts]\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Severity helps writers triage before you open a hundred tickets."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"building-a-canonical-glossary","__idx":3},"children":["Building a canonical glossary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example entry:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"## organization\nDefinition: A B2B customer workspace that owns subscriptions.\nUse: organization\nAvoid: tenant, account (unless referring to billing account)\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"encoding-terms-as-cli-rules","__idx":4},"children":["Encoding terms as CLI rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Subjective audits do not scale in CI. After humans agree on terms, express checks with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/configurable-rules"},"children":["configurable rules"]}," in your ruleset. Start from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/recommended"},"children":["recommended ruleset"]}," and extend. Run the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/commands/lint"},"children":["lint command"]}," on pull requests that touch docs or OpenAPI descriptions so violations fail before merge."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configurable rules work well for description fields and summary strings where the same forbidden token should never appear. They cannot understand context-heavy cases (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account"]}," in a banking doc may be correct). Keep a short exception list in the rule comments."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/guides/configure-rules"},"children":["guide to configuring a ruleset"]}," walks through first-time setup if your repository has no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," yet."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-policy-you-can-express","__idx":5},"children":["Example policy you can express"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Forbidden in summaries"},"children":["Forbidden in summaries"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Preferred"},"children":["Preferred"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["tenant"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["organization"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["B2B workspace"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["user"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["member"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["people inside an org"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["webhook URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["webhook endpoint"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["align with UI copy"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Start with three to five high-impact swaps. Expand after false positives are understood."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph LR\n A[AI terminology audit] --> B[Glossary in git]\n B --> C[CLI configurable rules]\n C --> D[CI lint on PRs]\n B --> E[Reunite remote content]\n E --> F[Published docs]\n","diagramHtml":"

AI terminology audit

Glossary in git

CLI configurable rules

CI lint on PRs

Reunite remote content

Published docs

","diagramHtmlDark":"

AI terminology audit

Glossary in git

CLI configurable rules

CI lint on PRs

Reunite remote content

Published docs

"},"children":["graph LR\n A[AI terminology audit] --> B[Glossary in git]\n B --> C[CLI configurable rules]\n C --> D[CI lint on PRs]\n B --> E[Reunite remote content]\n E --> F[Published docs]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Remote content keeps definitions synchronized with the glossary file."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reunite-remote-content-for-single-sourcing","__idx":6},"children":["Reunite remote content for single sourcing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a term appears in fifty pages, editing each file by hand fails. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/reunite/project/remote-content/remote-content"},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/realm/get-started/start-reunite-editor"},"children":["start with the Reunite editor"]}," and point them at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/reunite"},"children":["Reunite"]}," for the wider workflow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use remote content for definitions and boilerplate, not for entire guides, so diffs stay readable."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":7},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run terminology audits after rebrands or major UI copy changes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Separate audit (find conflicts) from rewrite (fix prose) into two PR types."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pair CLI bans with positive examples in the glossary."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Review false positives monthly and narrow rules instead of disabling lint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Invite support and developer relations to the glossary review so customer-facing language matches docs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Publish the glossary URL in your pull request template checklist for doc authors."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When remote content updates a definition, run lint on consuming projects the same day."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Export audit tables to CSV so product and support can comment without learning git syntax."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-lint-cannot-catch","__idx":8},"children":["What lint cannot catch"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":9},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-more","__idx":10},"children":["Learn more"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Explore Redocly CLI"]}," to wire configurable terminology rules into the same lint workflow you already use for OpenAPI validation."]}]},"headings":[{"value":"Use AI to check terminology consistency across your docs","id":"use-ai-to-check-terminology-consistency-across-your-docs","depth":1},{"value":"How the same concept gets three names","id":"how-the-same-concept-gets-three-names","depth":2},{"value":"AI audit prompt for terminology","id":"ai-audit-prompt-for-terminology","depth":2},{"value":"Building a canonical glossary","id":"building-a-canonical-glossary","depth":2},{"value":"Encoding terms as CLI rules","id":"encoding-terms-as-cli-rules","depth":2},{"value":"Example policy you can express","id":"example-policy-you-can-express","depth":3},{"value":"Reunite remote content for single sourcing","id":"reunite-remote-content-for-single-sourcing","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"What lint cannot catch","id":"what-lint-cannot-catch","depth":2},{"value":"Summary","id":"summary","depth":2},{"value":"Learn more","id":"learn-more","depth":2}],"frontmatter":{"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."}},"lastModified":"2026-05-22T12:10:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/learn/ai-for-docs/ai-check-terminology-consistency-across-docs","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}