Terminology Consistency — Managing Words and Phrases in Technical Documentation

In this tutorial, you will learn about Terminology Consistency. We cover key concepts, practical examples, and best practices to help you master this topic.

Terminology consistency means using the same words and phrases to describe the same concepts throughout your documentation. Inconsistent terminology confuses readers and makes documentation appear unprofessional.

In this lesson, you will learn how to create and maintain a terminology management system for your documentation.

What You'll Learn

You will understand why terminology consistency matters, create word lists and glossaries, and enforce terminology rules automatically.

Why It Matters

When documentation calls the same thing API key in one place and authentication token in another, readers wonder if they are different. Inconsistent terminology creates confusion and support tickets.

Real-World Use

DodaTech maintains a terminology database that powers automated checks. Writers get warnings when they use non-preferred terms. Consistency across all product documentation improved from 60 percent to 95 percent.

flowchart LR
  A[Word List] --> B[Preferred Terms]
  A --> C[Deprecated Terms]
  A --> D[Product Names]
  B --> E[Consistent Docs]
  C --> F[Flagged in Review]
  D --> G[Brand Compliance]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Creating a Word List

A word list defines preferred terms and their usage across documentation. Include terms that writers commonly confuse or use inconsistently.

For each term, specify the preferred form, deprecated alternatives, and usage notes. Include product names with correct capitalization. Include common misspellings.

Store the word list in your documentation Repository along with configuration for automated checking tools.

# DodaTech Terminology Word List

| Preferred Term | Deprecated Terms | Usage Notes |
|---------------|-----------------|-------------|
| sign in | login, log in | Verb form. Use sign in to for actions. |
| setup (noun) | set-up | For the configuration state. |
| set up (verb) | setup | For the action of configuring. |
| API key | api_key, API token, token | Use consistently for authentication. |
| DodaZIP | Doda Zip, DodaZip | Product name: all caps ZIP. |
| plugin | plug-in | Modern convention. |

Acronym Management

Always expand an acronym on first use per page. Write Network File System NFS before using NFS alone. Some well-known acronyms like HTML or API do not need expansion.

Maintain a list of approved acronyms. Add new acronyms only when necessary. Avoid creating acronyms that are used only once.

Be consistent with articles: a API versus an API depends on pronunciation. Use a before consonant sounds and an before vowel sounds.

# Vale configuration for acronym checking
# This enforces acronym expansion on first use.

extends: existence
message: Use the full form before the acronym.
link: https://developers.google.com/style/acronyms
level: error
ignorecase: true
tokens:
  - NFS
  - API
  - CLI
  - GUI

Common Mistakes

1. Synonym Overload

Using API key, token, auth code, and credential for the same thing. Choose one term and use it consistently.

2. Inconsistent Capitalization

Writing dodaZip, DodaZip, and dodazip in different places. Define the canonical form and enforce it.

3. Acronym Without Expansion

Using NFS without first writing Network File System. Always expand on first use per page.

4. Mixing Spellings

Using both setup and set-up for the same meaning. Pick one and use it everywhere.

5. No Word List

Relying on writers to remember preferred terms. A written word list prevents inconsistency.

6. Manual Enforcement Only

Human reviewers cannot catch every inconsistency. Automate terminology checking.

7. Never Updated Word List

A word list written once and never updated. Terminology evolves as products change.

Practice Questions

1. What is terminology consistency?

Using the same words and phrases to describe the same concepts throughout documentation. It prevents confusion and maintains professionalism.

2. What should a word list contain?

Preferred terms, deprecated alternatives, product names with correct capitalization, and usage notes.

3. When should you expand an acronym?

On first use per page. Write the full form followed by the acronym in parentheses.

4. How can terminology consistency be enforced automatically?

Using prose linters like Vale with custom rules that flag non-preferred terms.

5. Challenge: Audit a documentation set for terminology inconsistencies. Find at least 10 cases where the same concept is called different things. Create a word list entry for each inconsistency specifying the preferred term.

FAQ

Mini Project

Create a terminology word list for a project you know. Include at least 20 entries with preferred terms, deprecated alternatives, and usage notes. Configure a Vale rule to flag deprecated terms. Test the rule on existing documentation.

What's Next

Next: Tone: Formal vs Conversational