Recommended word list
To help ensure consistency across our 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 this phrase is implied. The phrase can also prematurely disclose 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 in a documentation page. If required, use following
instead.
For example:
In the following example, the dog had fleas.
checkbox
Use one word for checkbox
. Do not use check box
.
You select (not check or enable) and clear (not deselect or disable) checkboxes.
click
Do not 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
Do not use currently
when talking about the product or its features. The documentation describes the product as it is today.
deselect
Don’t use deselect
. Instead, use clear
.
disable
Do not use disable
. Implies that disability is a less-desired or negative state.
Instead, use turn off
or toggle off
.
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
Do not use enable
. Implies that disability is a less-desired or negative state.
Instead, use turn on
or toggle on
.
execute
Avoid where possible. Use run
instead.
K8s
Do not use. Use Kubernetes
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 register
instead of sign up 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
or log on
or log in
. If the user interface has different words, use those.
Also use sign in to
instead of sign into
.
sign up
Use register
or create account
instead of sign up
when talking about creating an account.
toggle
You turn on or turn off a toggle. For example:
Turn on the dark mode toggle.
upgrade
Use upgrade
for when describing a higher subscription tier
vs.
Don’t use vs.
as an abbreviation for versus; instead, use the unabbreviated versus
.
we
Try to avoid we
and focus instead on how the user can accomplish 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.