From b5f599265d5e6ed4ce6870dfa4464d48f510221a Mon Sep 17 00:00:00 2001 From: Chris Moore <107723039+cwillum@users.noreply.github.com> Date: Tue, 7 Feb 2023 08:53:25 -0800 Subject: [PATCH] Revise rules for the use of enable and disable (#2701) * fix#2695-disable-enable-ok Signed-off-by: cwillum * fix#2695-disable-enable-ok Signed-off-by: cwillum * fix#2695-disable-enable-ok Signed-off-by: cwillum --------- Signed-off-by: cwillum --- STYLE_GUIDE.md | 4 ++-- TERMS.md | 16 ++++++++++++++-- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 706eeed2..46ed2a42 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -427,8 +427,8 @@ The following terms may be problematic *in some contexts*. This doesn’t mean t |--------------------------|-------------------------------------| | blackout | service outage, blocked | | demilitarized zone (DMZ) | perimeter network, perimeter zone | -| disable | Use *turn off*, *deactivate*, or *stop* instead of *disable* to support bias-free documentation, when possible. Otherwise, use *disable* to describe making a feature or command unavailable. If the UI uses *active* and *inactive* to describe these states, use *activate* and *deactivate* in the documentation. Don't use *disable* to refer to users. | -| enable | Use *turn on*, *activate*, or *start* instead of *enable* to support bias-free documentation, when possible. Otherwise, use *enable* to describe making a feature or command available. If the UI uses *active* and *inactive* to describe these states, use *activate* and *deactivate* in the documentation.

Avoid using *enable* to refer to making something possible for the user. Instead, rewrite to focus on what's important from the user's point of view. For example, “With ABC, you can do XYZ” is a stronger statement than “ABC enables you to XYZ.” Additionally, using a task-based statement is usually more clear than the vague “…enables you to….” | +| disable | You can use *disable* to describe making a feature or command unavailable. Don't use *disable* to refer to users. | +| enable | You can use *enable* to describe making a feature or command available.

Avoid using *enable* to refer to making something possible for the user. Instead, rewrite to focus on what's important from the user's point of view. For example, “With ABC, you can do XYZ” is a stronger statement than “ABC enables you to XYZ.” Additionally, using a task-based statement is usually more clear than the vague “…enables you to….” | | invalid | not valid | | primitive | Avoid using *primitive* (especially plural *primitives*) as a colloquial way of referring to the basic concepts or elements that are associated with a feature or to the simplest elements in a programming language. For greatest clarity and to avoid sounding unpleasant, replace with *primitive data type* or *primitive type*. | | purge | Use only in reference to specific programming methods. Otherwise, use *delete*, *clear*, or *remove* instead. | diff --git a/TERMS.md b/TERMS.md index 4fc0812c..a4312003 100644 --- a/TERMS.md +++ b/TERMS.md @@ -203,7 +203,14 @@ Use to describe a list of items that aren’t allowed (blocked). Do not use _bla **disable** -Use *turn off*, *deactivate*, or *stop* instead of *disable* to support bias-free documentation, when possible. Otherwise, use *disable* to describe making a feature or command unavailable. If the UI uses *active* and *inactive* to describe these states, use *activate* and *deactivate* in the documentation. Don't use *disable* to refer to users. +Use *disable* to describe making a feature or command unavailable. For example: + +- Clear the checkbox to disable automatic monitoring. +- The feature is disabled by default. + +Note that alternatives to *disable*—such as *deactivate*, *turn off*, or *stop*—are acceptable usage where appropriate and may be found in existing documentation. In all cases, use language that corresponds to the language used in the UI, if applicable. + +Do not use *disable* to refer to users. **double-click** @@ -233,7 +240,12 @@ Use as a singular noun or adjective to refer to the collective concept, and use **enable** -Use _turn on_ or _activate_ instead of *enable* to support bias-free documentation, when possible. Otherwise, use *enable* to describe making a feature or command available. If the UI uses *active* and *inactive* to describe these states, use *activate* and *deactivate* in the documentation. +Use *enable* to describe making a feature or command available. For example: + +- Select the checkbox to enable automatic monitoring. +- The feature is enabled by default. + +Note that alternatives to *enable*—such as *activate*, *turn on*, or *start*—are acceptable usage where appropriate and may be found in existing documentation. In all cases, use language that corresponds to the language used in the UI, if applicable. Avoid using *enable* to refer to making something possible for the user. Instead, rewrite to focus on what's important from the user's point of view. For example, “With ABC, you can do XYZ” is a stronger statement than “ABC enables you to XYZ.” Additionally, using a task-based statement is usually more clear than the vague “…enables you to….”