Recommended word list
To help ensure consistency across documentation, the Technical Writing team recommends these wording choices.
& (ampersand)
Don't use & instead of and in headings, text, navigation, UI copy, or tables of contents.
above
Try to avoid using above when referring to an example or table in a documentation page. If required, use previous instead.
For example:
In the previous example, the dog had fleas.
account name
Don't use. Instead, use username.
admin
Write out administrator on first use. Use admin if it's the name of a UI label or other element.
allows
Don't use. Instead, use lets.
as of this writing
Avoid because the writing itself implies this phrase. The phrase can also prematurely share product or feature strategy or inappropriately imply that a product or feature might change.
below
Try to avoid below when referring to an example or table on a documentation page. If required, use following instead.
For example:
In the following example, the dog had fleas.
checkbox
Use one word for checkbox. Don't use check box.
You select (not check or enable) and clear (not deselect or disable) checkboxes.
click
Don't use click. Instead, use select with buttons, links, menu items, and lists.
Select applies to more devices, while click is more specific to a mouse.
currently
Don't use currently when talking about the product or its features. The documentation describes the product as it is today.
disable
Don't use disable. Implies that disability is a less-desired or negative state.
Instead, use turn off or toggle off.
There are times with more technical features when the development team uses disable, and in these cases, it's OK to use the term.
earlier
Use earlier when talking about version numbers.
Use:
In Docker Desktop 4.1 and earlier.
Instead of:
In Docker Desktop 4.1 and lower.
easy, easily
What might be easy for you might not be easy for others. Try eliminating this word from the sentence because usually the same meaning can be conveyed without it.
e.g.
Don't use. Instead, use phrases like for example or such as.
enable
Don't use enable. Implies that disability is a less-desired or negative state.
Instead, use turn on or toggle on.
There are times with more technical features when the development team uses enable, and in these cases, it's OK to use the term.
execute
Avoid where possible. Use run instead.
later
Use later when talking about version numbers.
Use:
In Docker Desktop 4.1 and later.
Instead of:
In Docker Desktop 4.1 and higher… or In Docker Desktop 4.1 and above…
please
Don't use please in the normal course of explaining how to use a product, even if you're explaining a difficult task. Also don't use the phrase please note.
register
Use sign up instead of register when talking about creating an account.
repo
Don't use. Instead, use repository.
respectively
Avoid respectively and be more precise instead.
scroll
Avoid. Use a verb phrase such as move through or navigate to instead, if the context is clear.
sign in
Use sign in instead of sign on, signon, log on, logon, or log in, login. If the user interface uses different words, use those.
Use sign in to instead of sign into.
sign up
Use sign up or create account instead of register when talking about creating an account.
tab versus view
Use view when referring to a major section in a UI. Use tab when referring to a sub-section in the UI.
For example, in Docker Desktop, the Images view and the Local tab.
toggle
You turn on or turn off a toggle. For example:
Turn on the dark mode toggle.
upgrade
Use upgrade when describing a higher subscription tier
vs
Don't use vs or vs. as an abbreviation for versus; instead, use the unabbreviated versus.
we
Try to avoid we and focus instead on how the user can carry out something in Docker.
Use:
Use widgets when you have work you want to organize.
Instead of:
We created a feature for you to add widgets.
wish
Don't use. Use want instead.