Skip to main content

Word and Acronym Usage

Last updated on
Open a doc issue   |   Edit this page

Effective communication hinges on proper word usage. This guide offers tips for using words effectively, ensuring clarity, accuracy, and accessibility.

By following these guidelines, you can enhance reader comprehension and user experience. Learn to refine your writing, from avoiding ambiguity to handling acronyms, to communicate more effectively with your audience.

Effective word usage

Effective and proper word usage ensures clarity, accuracy, and accessibility, enhancing reader comprehension and user experience.

Avoid "and/or"

Rewrite the sentence to clarify the meaning.

note

The word or can mean either or both, which can make the content confusing.

Correct

You can configure the server for HTTP, HTTPS, or both.

Install the software on Windows, Linux, or on both operating systems.

Incorrect

You can configure the server for HTTP and/or HTTPS.

Install the software on Windows and/or Linux.

Avoid "please"

Starting with "Please" makes the instruction sound passive and less direct, and often unnecessary. In technical environments, clarity and precision are valued more than politeness.

Correct

Enter the component name.

Why this is better: This version is straightforward and removes unnecessary formality. It gets to the point and respects the user's time.

Incorrect

Please enter the name of the component.

Avoid "may"

  • Use can to indicate ability.
  • Use might to indicate possibility.

Correct

You can use the command line interface to update your app framework.

You might need more advanced features when you integrate with another app.

Incorrect

You may use the command line interface to update your application.

You may need more advanced features when you integrate with another application.

Use "ensure" or "confirm"

  • Use ensure in cases where there's still a related important task.
  • Use confirm in cases where the user has already been told to do something, and you're now reminding them.

Correct

Ensure the server is running before deploying the application.

Confirm you've entered the correct user credentials before continuing.

Incorrect

Verify that the server is running before deploying the application.

Check if you've entered the correct user credentials before clicking Submit.

Click vs. Select vs. Choose

  • Use select to instruct the user to select a specific UI element, like a button.
  • Use choose to instruct the user to choose an option that's based on their preference or desired outcome.
  • Avoid click because it's specific to using a mouse. Instead, use verbs that work with multiple devices, such as select or choose.
  • Avoid highlight or pick.

Press vs. Hit

  • Avoid hit or press to refer to pressing a key. Use select instead.
  • Use press to imply pushing a physical button on hardware.

Acronyms and abbreviations

Acronyms and abbreviations can hurt clarity, voice, and findability. Although some acronyms are widely understood and preferred to the spelled-out term, others aren't well known or are familiar only to a specific group of users.

Spell out the first instance

Spell it out for clarity and followed by the acronym or abbreviation in parentheses and use acronym or abbreviation on subsequent mentions in the same article/page/document.

  • If an acronym will appear only once in your content, only spell it out.
  • Lowercase all words in the spelled-out form of any acronym except for proper nouns.

Correct

infrastructure as a service (IaaS)

dynamic-link library (DLL)

Incorrect

Infrastructure as a Service (IaaS)

Dynamic-Link Library (DLL)

Latin abbreviations

Use the full English form of Latin abbreviations. While "i.e.," is commonly used, spelling out "that is" enhances clarity, especially for readers who might night be familiar with the abbreviation.

  • Replace "e.g.," with "for example," making the sentence clearer to all readers, especially those who may not be familiar with Latin abbreviations.
  • As an exception to this rule, the abbreviation "etc." is allowed.

Correct

You may need to reset the device, that is, turn it off and on again.

Use a strong encryption method, for example, AES or RSA.

Incorrect

You may need to reset the device, i.e., turn it off and on again.

Use a strong encryption method, e.g., AES or RSA.

"v" for version

Use lowercase "v" for version numbers because it is the standard convention for technical documentation. This convention is popular because it's simple, clean, and doesn't call too much attention to the version prefix.

Avoid using an uppercase "V" since this is more prominent in marketing documentation, which aligns with branding rules. In this case, it represents a milestone rather than a functional increment that's most common in technical contexts.

Correct

SonarQube Scanner upgrade from v4.8 to v6.0

Incorrect

SonarQube Scanner Upgrade from V4.8.x to V6.0.x