Word usage and terminology

Consistent terminology is essential for clear, accurate, and professional technical content. When terms shift or vary, users lose confidence, AI systems misinterpret meaning, and documentation becomes harder to maintain. A strong terminology framework ensures every writer, editor, designer, developer, and AI assistant uses language the same way.

This section outlines best practices for terminology management and precise word usage in technical communication.

Preferred terminology

Use a single, approved term for each concept. Avoid synonyms, abbreviations, and variations unless defined as acceptable alternatives.

Examples:

• Preferred: knowledge base
  Avoid: KB, help center, docs hub

• Preferred: category manager
  Avoid: folder manager

Using consistent terms improves readability, reduces ambiguity, and helps search engines and AI tools correctly index and interpret content.

Terminology management best practices

1. Maintain a terminology list or glossary
   Include definitions, preferred terms, allowed alternatives, disallowed terms, and usage notes.

2. Use terms consistently across all channels
   Documentation, UI text, release notes, support articles, in-product messages, marketing content, and AI responses should follow the same terminology rules.

3. Define new terms before using them
   When introducing a technical concept, explain it clearly the first time.

4. Avoid creating unnecessary synonyms
   Pick one term and apply it consistently.

5. Update terminology regularly
   As technology evolves, terms must evolve with it.

6. Ensure terminology supports global audiences
   Avoid idioms, unclear abbreviations, or culturally specific naming.

Style preferences

Use plain language

Choose simple, direct words that all users can understand.

• Preferred: click

• Avoid: utilize

Avoid unnecessary jargon

Use technical terms only when required and define them clearly.

Use gender-neutral language

• Preferred: they

• Avoid: he/she

Maintain a professional tone

Avoid slang, idioms, colloquialisms, or overly casual expressions.

UI terminology

Use clear and consistent labels for UI elements.
Avoid inventing new terms or using inconsistent phrasing.

Examples:

• Use button, menu, tab, panel, dialog, notification, error message consistently.

• Don’t mix similar terms unless they have distinct meanings in the product.

Consistency

Consistency is the core of reliable technical writing.

• Use the same term for the same concept every time.

• Align terminology across all documentation and interface text.

• Ensure writers and reviewers refer to the approved glossary.

• Apply the rules consistently in human-written and AI-generated content.

Special considerations

• Terminology should reflect the product accurately.
  When the product changes, update the terms and definitions.

• Be mindful of searchability.
  Consistent terminology improves internal search, SEO, and AI-assisted retrieval.

• Machine readability matters.
  AI agents rely on consistent terminology to extract, index, and surface information accurately.