Acronyms, jargon, and specialized terminology

Last updated
Save as PDF

Specialized language can cause incorrect AI responses, because the unique vocabulary that is obvious to an industry, product, or team is incomprehensible to audiences outside of those groups, such as readers and AI models. If an article uses an acronym or term without defining it, AI cannot connect it to a reader's question.

Spell out acronyms

The first time an acronym appears in an article, write out the full term and put the acronym in parentheses after it. From that point on in the same article, you can use the acronym alone.

Example:

Before: "The WFH policies reflect input from the employee survey."
If the reader does not know that WFH means "work from home," this sentence is useless. A search for "work from home policy" may not surface this article at all.

After: "The work from home (WFH) policies reflect input from the employee survey."
Now the article works for readers who know the acronym, readers who don't, and AI processing a query that uses either term.

Maintain a glossary

For acronyms and terms that appear across many articles, create a glossary article that defines each one clearly. This gives the AI a single, authoritative source for the meaning of each term, and enables users to look up unfamiliar language in one place.

You must still define acronyms inline the first time they appear in each article. The glossary is a backup, not a substitute; the inline definition is what makes an individual article self-contained.

Define industry jargon

Acronyms are a more obvious source of confusion, but full words can be just as problematic. Words like "onboarding," "provisioning," "escalation," or "tenant" have specific meanings in some contexts and different or no meanings in others.

If a term is specific to your product, industry, or team, define it the first time you use it in an article.

Example:

Before: "To provision a new tenant, use the admin console."

After: "To create a new customer environment (called a "tenant") in the system, use the admin console."

The "after" version teaches the reader what "tenant" means in this product. A customer who asks "How do I create a new customer environment?" can now be matched to this article, even though they did not use the word "tenant."

Watch for internal-only language

Team names, project codenames, ticket references, and internal tool names do not belong in customer-facing articles. Read a page as if you were a new customer or onboarding employee. Anywhere you see a word or phrase someone might not recognize, replace or define it.

Example:

Before: "If the Falcon service returns a 503, escalate to the Platform pod via a P2 ticket."

After: "If the checkout service returns an error indicating it is unavailable, contact platform support. Include the time of the error and the customer's order number."