Updates style guide and terms (#3980)

* Updates style guide and terms

Signed-off-by: natebower <102320899+natebower@users.noreply.github.com>

* Adds term

Signed-off-by: natebower <102320899+natebower@users.noreply.github.com>

* Adds guidance

Signed-off-by: natebower <102320899+natebower@users.noreply.github.com>

---------

Signed-off-by: natebower <102320899+natebower@users.noreply.github.com>
This commit is contained in:
Nathan Bower 2023-05-04 13:09:26 -04:00 committed by GitHub
parent 72203306d4
commit 20c87bb150
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 12 additions and 2 deletions

View File

@ -64,6 +64,8 @@ Whenever possible, use the active voice instead of the passive voice. The passiv
Refer to the reader as _you_ (second person), and refer to the OpenSearch Project as _we_ (first person). If there are multiple authors for a blog post, you can use _we_ to refer to the authors as individuals.
Describe the actions that the user takes, rather than contextualizing from the feature perspective. For example, use phrases such as “With this feature, you can...” or “Use this feature to...” instead of saying a feature *allows*, *enables*, or *lets* the user do something.
For procedures or instructions, ensure that action is taken by the user (“Then you can stop the container...”) rather than the writer (“We also have to stop the container...”). Reserve the first-person plural for speaking as the OpenSearch Project, with recommendations, warnings, or explanations.
In general, use the present tense. Use the future tense only when an event happens later than, not immediately after, the action under discussion.
@ -270,6 +272,8 @@ We follow a slightly modified version of the _Microsoft Writing Style Guide_ gui
- Words with prefixes are normally closed (no hyphen), whether they are nouns, verbs, adjectives, or adverbs. Note that some industry terms dont follow this hyphenation guidance. For example, *Command Line Interface* and *high performance computing* arent hyphenated, and *machine learning* isnt hyphenated when used as an adjective. Other terms are hyphenated to improve readability. Examples include *non-production*, *post-migration*, and *pre-migration*.
- In general, comparative or superlative modifiers with “more,” “most,” “less,” or “least” dont require hyphens. Use one only if its needed to avoid ambiguity.
- The ampersand (&) should never be used in a sentence as a replacement for the word and. An exception to this is in acronyms where the ampersand is commonly used, such as in Operations & Maintenance (O&M).
- When using a forward slash between words, do not insert space on either side of the slash. For example, *AI/ML* is correct whereas *AI / ML* is incorrect.
@ -420,8 +424,6 @@ The following terms may be problematic *in some contexts*. This doesnt mean t
|--------------------------|-------------------------------------|
| blackout | service outage, blocked |
| demilitarized zone (DMZ) | perimeter network, perimeter zone |
| 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. <br><br> 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. |

View File

@ -664,6 +664,14 @@ Data that's provided as part of a metric. The time value is assumed to be when t
Avoid using as a verb to refer to an action that precipitates a subsequent action. It is OK to use when referring to a feature name, such as a *trigger function* or *time-triggered architecture*. As a verb, use an alternative, such as *initiate*, *invoke*, *launch*, or *start*.
**turn on, turn off**
Use *turn on* and *turn off* in reference to a toggle to describe switching a setting or mode on or off.
Don't use *choose*, *select*, *clear*, *slide*, *enable*, or *disable* for a toggle.
For making a feature available or unavailable, use *enable*.
## U
**UltraWarm**