Recommended Word List for Technical Documentation

--- title: Recommended word list description: Recommended word list for Technical documentation keywords: recommended word list, style guide, contribute weight: 30 --- 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.

The Technical Writing team recommends specific wording choices to ensure consistency across documentation. This includes avoiding certain terms like '&', 'above', 'account name', 'allows', and 'currently', and suggesting alternatives like 'and', 'previous', 'username', 'lets', and removing 'currently' altogether. It also specifies using 'administrator' on first use and 'admin' thereafter, and to use 'select' instead of 'click'. When referring to items that are checked or unchecked, use 'select' and 'clear' instead of 'check' or 'disable'.