Add OpenSearch Style Guide (#657)
* Add Style Guide to repo Signed-off-by: Naarcha-AWS <naarcha@amazon.com> * Rename Style Guide to match contributing Signed-off-by: Naarcha-AWS <naarcha@amazon.com> * Remove duplicate style guide Signed-off-by: Naarcha-AWS <naarcha@amazon.com> * Make terms own page. Add and reorder sections Signed-off-by: Naarcha-AWS <naarcha@amazon.com> * Add offensive and sensitive terms Signed-off-by: Naarcha-AWS <naarcha@amazon.com> * Add final feedback Signed-off-by: Naarcha-AWS <naarcha@amazon.com> * Fix image link Signed-off-by: Naarcha-AWS <naarcha@amazon.com>
This commit is contained in:
Naarcha-AWS
GitHub
parent
8909564891
commit
d483a117d3
|
|
@ -0,0 +1,201 @@
|
|||
# OpenSearch style guidelines
|
||||
|
||||
Welcome to the content style guide for the OpenSearch project. This guide covers the style standards to be observed when creating OpenSearch content and will evolve as we implement best practices and lessons learned in order to best serve the community.
|
||||
|
||||
Our content is generally edited in accordance with the _AWS Style Guide_, the [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/), [The Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html), and [Merriam-Webster](https://www.merriam-webster.com/) (listed in order of precedence); however, we may deviate from these style guides in order to maintain consistency and accommodate the unique needs of the community. This is by no means an exhaustive list of style standards, and we value transparency, so we welcome contributions to our style standards and guidelines. If you have a question regarding our standards or adherence/non-adherence to the style guides or would like to make a contribution, please tag @natebower on GitHub.
|
||||
|
||||
## Voice and tone
|
||||
|
||||
Voice is the point of view or style of a writer. Voice can refer to active or passive but may also refer to verb tense (past, present, future, and so on). Tone is the emotional undercurrent (such as calm or angry) of the voice. We strive to speak to the community with a consistent voice and tone, as if a single writer writes all content. Writing with a common voice also helps to establish the OpenSearch identity and brand.
|
||||
|
||||
### Voice
|
||||
|
||||
The voice of OpenSearch is people-oriented and focused on empowering the end user directly. We use language that emphasizes what the reader can do with the software rather than what tasks the software can perform.
|
||||
|
||||
Whenever possible, use the active voice instead of the passive voice. The passive form is typically wordier and can often cause writers to obscure the details of the action. For example, change the agentless passive it is recommended to the more direct we recommend.
|
||||
|
||||
Refer to the reader as you (second person) and refer to the OpenSearch organization as we (first person). If there are multiple authors for a blog post, you can use we to refer to the authors as individuals.
|
||||
|
||||
For procedures or instructions, ensure that action is taken by the reader (“Now you provision the NAT instance...”) rather than the writer (“We also have to wait for the primary domain controller to...”). Reserve the first-person plural for speaking as OpenSearch, 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
|
||||
|
||||
### Tone
|
||||
|
||||
The tone of OpenSearch is direct and friendly. The overall tone is knowledgeable but humble, informal but authoritative, informative but not dry, and friendly without getting chatty.
|
||||
|
||||
We talk to readers in their own words, never assuming that they understand how our technology works. We use precise technical terms where appropriate, but we avoid technical jargon and insider lingo. We speak to readers in simple, plain, everyday language. Our messaging is judgment free; words like simple, easy, and just create a skill judgment that may not apply to everyone in the OpenSearch community.
|
||||
|
||||
Avoid excessive words, such as please. Be courteous but not wordy. Extra detail can often be moved elsewhere.
|
||||
|
||||
Use humor with caution because it is subjective, can be easily misunderstood, and can potentially alienate your audience.
|
||||
|
||||
As you write content, apply the following tone traits.
|
||||
|
||||
| **Trait** | **Approachable** | **Authoritative** | **Concise** | **Conversational** | **Directed** | **Respectful** | **Simple** | **Smart** | **Trustworthy** |
|
||||
|---|---|---|---|---|---|---|---|---|---|
|
||||
| **What it is** | Personable, Friendly, Welcoming, Genuine | Professional, Expert, Informed, Dependable, Validated | Succinct, Brief, Lean, To the point | Informal, Casual, Familiar, Matter-of-fact | Focused, Guided, Controlled, Purposeful, Predictable, Definitive, Essential | Considerate, Helpful, Supportive, Empathic | Plain, Everyday, Recognizable, Clear, Straightforward, Common | Knowledgeable, Logical, Correct, Consistent, Coherent, Grammatical, Polished | Reliable, Truthful, Fair, Candid |
|
||||
| **What it isn't** | Chatty, Hyperbolic, Cloying, Insincere | Stuffy, Dictatorial, Smug, Unsure, Untested | Wordy, Lengthy, Verbose, Rambling | Stilted, Pompous, Chummy, Pedantic | Vague, Wandering, Confusing, Ambiguous, Surprising, Indecisive, Redundant | Insulting, Condescending, Insensitive, Indifferent | Fancy, Esoteric, Perplexing, Unintelligible, Complicated, Unusual | Pedantic, Invalid, Inaccurate, Varying, Disorganized, Careless, Sloppy | Infallible, Evasive, Devious, Obfuscating |
|
||||
|
||||
## Style guidelines
|
||||
|
||||
The following guidelines should be observed in OpenSearch content.
|
||||
|
||||
### Punctuation and capitalization
|
||||
|
||||
- Use lowercase for nouns and noun phrases that are not proper nouns; for example, *big data*. This style follows the standard rules of American English grammar.
|
||||
|
||||
- For plural forms of nouns that end in “s”, form the possessive case by adding only an apostrophe.
|
||||
|
||||
- When a colon introduces a list of words, a phrase, or other sentence fragment, the first word following the colon is lowercased unless it is a proper name. When a colon introduces one or more complete sentences, the first word following it is capitalized. When text introduces a table, it should be a complete sentence and end with a period, not a colon.
|
||||
|
||||
- Use commas to separate the following:
|
||||
- Independent clauses separated by coordinating conjunctions (but, or, yet, for, and, nor, so).
|
||||
- Introductory clauses, phrases, words that precede the main clause.
|
||||
- Words, clauses, and phrases listed in a series. Also known as the Oxford comma.
|
||||
|
||||
- An em dash (—) is the width of an uppercase M. Do not include spacing on either side. Use an em dash to set off parenthetical phrases within a sentence or set off phrases or clauses at the end of a sentence for restatement or emphasis.
|
||||
|
||||
- An en dash (–) is the width of an uppercase N. In ranges, do not include spacing on either side. Use an en dash to indicate ranges in values and dates, separate a bullet heading from the following text in a list, or separate an open compound adjective (two compounds, only one of which is hyphenated) from the word that it modifies.
|
||||
|
||||
- Words with prefixes are normally closed (no hyphen), whether they are nouns, verbs, adjectives, or adverbs. Note that some industry terms don’t follow this hyphenation guidance. For example, *Command Line Interface* and *high performance computing* aren’t hyphenated, and *machine learning* isn’t hyphenated when used as an adjective. Other terms are hyphenated to improve readability. Examples include *non-production*, *post-migration*, and *pre-migration*.
|
||||
|
||||
- Use sentence case for topic titles. Titles of guides and references use title case.
|
||||
|
||||
- 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.
|
||||
|
||||
- When referring to API parameters, capitalize *Boolean*. Otherwise, primitive Java data types (*byte*, *short*, *int*, *long*, *float*, *double*, and *char*) start with a lowercase letter, while non-primitive types start with an uppercase letter.
|
||||
|
||||
### Numbers and measurement
|
||||
|
||||
- Spell out cardinal numbers from 1 to 9. For example, one NAT instance. Use numerals for cardinal numbers 10 and higher. Spell out ordinal numbers: first, second, and so on. In a series that includes numbers 10 or higher, use numerals for all. Use a comma separator for numbers of four digits or more—for example, 1,000.
|
||||
|
||||
- For descriptions that include time ranges, separate the numbers with an en dash. Avoid extra words such as between or from n to n.
|
||||
- Correct: It can take 5–10 minutes before logs are available.
|
||||
- Incorrect: It can take between 5 and 10 minutes before logs are available.
|
||||
|
||||
- Use numerals for all measurement-based references, including time. Include a space between the number and the abbreviation for the unit of measure.
|
||||
- Correct:
|
||||
- 100 GB
|
||||
- 1 TB
|
||||
- 3 minutes
|
||||
- 12 subnets (8 public and 4 private)
|
||||
- Incorrect
|
||||
- One hundred GB
|
||||
- 1TB
|
||||
|
||||
### Formatting and organization
|
||||
|
||||
- When referring to fields in the API, use the following format: time_field
|
||||
|
||||
- The following guidelines apply to all list types:
|
||||
- Make lists parallel in content and structure. Don’t mix single words with phrases, don’t start some phrases with a noun and others with a verb, and don’t mix verb forms.
|
||||
- Present the items in alphabetical order if the order of items is arbitrary.
|
||||
- Capitalize the first letter of the first word of each list item.
|
||||
- If the list is simple, you don’t need end punctuation for the list items.
|
||||
- If the list has a mixture of phrases and sentences, punctuate each list item.
|
||||
- Punctuate each list item with a period if a list item has more than one sentence.
|
||||
- Punctuate list items consistently. If at least one item in a list requires a period, use a period for all items in that list.
|
||||
- Titles are optional for most lists. If used, the title comes after an introductory sentence.
|
||||
- Titles are highly recommended for procedures. Avoid titles for bulleted lists.
|
||||
- Introductory sentences are required for lists.
|
||||
- Introductory sentences should be complete sentences.
|
||||
- Introductory sentences should end with a period if the list has a title.
|
||||
- Introductory sentences should end with a colon if the list does not have a title.
|
||||
- Don’t use semicolons, commas, or conjunctions (like and or or) at the end of list items.
|
||||
|
||||
- Start all task-based headings with an infinitive. For example: “Create an index”. For conceptual sections, use a noun phrase. For example: “Migration to OpenSearch 2.0”
|
||||
|
||||
- Stacked headings should never appear in our content. Stacked headings are any two consecutive headings without intervening text. Even if it is just an introductory sentence, there should always be text under any heading.
|
||||
|
||||
### Procedures
|
||||
|
||||
A procedure is a series of numbered steps that a user follows to complete a specific task. Users should be able to scan for and recognize procedures easily. Make procedures recognizable by using the following:
|
||||
|
||||
- Predictable content parts
|
||||
- Parallel language constructions
|
||||
- Consistent formatting
|
||||
|
||||
Following is an example of procedure phrasing and formatting from Amazon EC2.
|
||||
|
||||
|
||||
|
||||
### Miscellaneous
|
||||
|
||||
- Use contractions carefully for a more casual tone. Use common contractions. Avoid future tense (I’ll), archaic (‘twas), colloquial (ain’t), or compound (couldn’t’ve) contractions.
|
||||
|
||||
- Use italics for the titles of books, periodicals, and reference guides. However, do not use italics when the title of a work is also a hyperlink.
|
||||
|
||||
- On first use, acronyms should always be defined; for example, _access control list (ACL)_. The acronym itself should be used for subsequent appearances; for example, _ACL_. Some acronyms, like _IT_ and _CPU_, are commonly understood and do not need to be defined. Do not capitalize the spelled-out form of an acronym unless the spelled-out form is a proper noun or the community generally capitalizes it. In all cases, our usage should reflect the community’s usage.
|
||||
|
||||
- We may not alter quotations in any way. This includes defining acronyms within the quote or altering the quote for context.
|
||||
|
||||
## Special considerations for blog posts
|
||||
|
||||
Blog posts provide an informal approach to educating or inspiring readers through the personal perspective of the authors. Brief posts generally accompany service or feature releases, and longer posts may note best practices or provide creative solutions. Each post must provide a clear community benefit.
|
||||
|
||||
To enhance the strengths of the blogging platform, follow these post guidelines:
|
||||
|
||||
**Be conversational and informal.**
|
||||
|
||||
Posts tend to be more personable, unlike technical documentation. Ask questions, include relevant anecdotes, add recommendations, and generally try to make the post as approachable as possible. However, be careful of slang, jargon, and phrases that a global audience might not understand.
|
||||
|
||||
**Keep it short.**
|
||||
|
||||
Deep topics don’t necessarily require long posts. Shorter, more focused posts are easier for readers to digest. Consider breaking a long post into a series, which can also encourage repeat visitors to the blog channel.
|
||||
|
||||
**Avoid redundancy.**
|
||||
|
||||
Posts should add to the conversation. Instead of repeating content that is already available elsewhere, link to detail pages and technical documentation. Keep only the information that is specific to the post solution or recommendations.
|
||||
|
||||
**Connect with other content.**
|
||||
|
||||
All posts should contain one or more calls to action that give readers the opportunity to create resources, learn more about services or features, or connect with other community members. Posts should also include metadata tags such as services, solutions, or learning levels to help readers navigate to related content.
|
||||
|
||||
## Inclusive content
|
||||
|
||||
OpenSearch content strives to be inclusive and free of bias. We use inclusive language to connect with the diverse and global OpenSearch audience. This means we are careful in our word choices. Inclusive and bias-free content improves clarity and accessibility of our content for all audiences. We avoid ableist and sexist language and language that perpetuates racist structures or stereotypes.
|
||||
|
||||
### Offensive terms
|
||||
|
||||
Do _not_ use the following terms.
|
||||
|
||||
| Don’t use | Use instead |
|
||||
|----------------|-----------------------------|
|
||||
| abort | stop |
|
||||
| black day | blocked day |
|
||||
| blacklist | deny list |
|
||||
| execute | start, run |
|
||||
| hang | stop responding |
|
||||
| kill | end, stop |
|
||||
| master | primary, main, leader |
|
||||
| master account | management account |
|
||||
| slave | replica, secondary, standby |
|
||||
| white day | open day |
|
||||
| whitelist | allow list |
|
||||
|
||||
|
||||
### Sensitive terms
|
||||
|
||||
Avoid using the following terms.
|
||||
|
||||
| Avoid using | Use instead |
|
||||
|--------------------------|-------------------------------------|
|
||||
| blackout | service outage, blocked |
|
||||
| demilitarized zone (DMZ) | perimeter network, perimeter zone |
|
||||
| disable | turn off, deactivate, stop |
|
||||
| enable | turn on, activate, start |
|
||||
| invalid | not valid |
|
||||
| primitive | primitive data type, primitive type |
|
||||
| purge | delete, clear, remove |
|
||||
| segregate | separate, isolate |
|
||||
| trigger | initiate, invoke, launch, start |
|
||||
| white day | open day |
|
||||
| whitelist | allow list |
|
||||
|
||||
## Trademark policy
|
||||
|
||||
The “OpenSearch” word mark should be used in its exact form and not abbreviated or combined with any other word or words (e.g., “OpenSearch” software rather than “OPNSRCH” or “OpenSearch-ified”). See the [OpenSearch Trademark Policy](https://opensearch.org/trademark-usage.html) for more information. Also refer to the policy and to the [OpenSearch Brand Guidelines](https://opensearch.org/brand.html) for guidance regarding the use of the OpenSearch logo. When using another party’s logo, refer to that party’s trademark guidelines.
|
||||
|
||||
|
|
@ -0,0 +1,559 @@
|
|||
# OpenSearch terms
|
||||
|
||||
This is how we use our terms, but we’re always open to hearing your suggestions.
|
||||
|
||||
## A
|
||||
|
||||
**ad hoc**
|
||||
|
||||
Avoid. Use *one-time* instead.
|
||||
|
||||
**affect**
|
||||
|
||||
Affect as a noun refers to emotion as expressed in face or body language. Affect as a verb means to influence. Do not confuse with effect.
|
||||
|
||||
**AI/ML**
|
||||
|
||||
On first mention, use artificial intelligence and machine learning (AI/ML).
|
||||
|
||||
**Alerting**
|
||||
|
||||
A plugin that notifies you when data from one or more OpenSearch indexes meets certain conditions.
|
||||
|
||||
**allow**
|
||||
|
||||
Use allow when the user must have security permissions in order to complete the task.
|
||||
|
||||
Avoid using allow to refer to making something possible for the user. Instead, rewrite to focus on what’s important from the user’s point of view.
|
||||
|
||||
**allow list**
|
||||
|
||||
Use to describe a list of items that are allowed (not blocked). Do not use as a verb. Do not use whitelist.
|
||||
|
||||
**Amazon OpenSearch Service**
|
||||
|
||||
Amazon OpenSearch Service is a managed service that makes it easy to deploy, operate, and scale OpenSearch clusters in the AWS Cloud. Amazon OpenSearch Service is the successor to Amazon Elasticsearch Service (Amazon ES) and supports OpenSearch and legacy Elasticsearch OSS (up to 7.10, the final open-source version of the software).
|
||||
|
||||
**Anomaly Detection**
|
||||
|
||||
A plugin that automatically detects anomalies in your OpenSearch data in near real time.
|
||||
|
||||
**API**
|
||||
|
||||
application programming interface
|
||||
|
||||
**API operation**
|
||||
|
||||
Use instead of action, method, or function.
|
||||
|
||||
OpenSearch style:
|
||||
|
||||
- Use the CopySnapshot operation to...
|
||||
- The following API operations…
|
||||
|
||||
Not OpenSearch style
|
||||
|
||||
- Use the CopySnapshot action to...
|
||||
- Use the CopySnapshot method to...
|
||||
- Use the CopySnapshot function to...
|
||||
|
||||
**app or application**
|
||||
|
||||
Use app for mobile software, application for all other uses.
|
||||
|
||||
**appear, display, and open**
|
||||
|
||||
Messages and pop-up boxes appear. Windows, pages, and applications open. The verb display requires a definite object. For example: The system displays the error message.
|
||||
|
||||
**application server**
|
||||
|
||||
Do not abbreviate as app server.
|
||||
|
||||
**as well as**
|
||||
|
||||
Avoid. Replace with in addition to or and as appropriate.
|
||||
|
||||
**Asynchronous Search**
|
||||
|
||||
A plugin that lets the user send search requests in the background so that the results can be used later.
|
||||
|
||||
**auto scaling**
|
||||
|
||||
Lower case scaling, auto scaling, and automatic scaling (but not autoscaling) are the preferred descriptive terms when generically describing auto scaling functionality.
|
||||
|
||||
Do not use hyphenated auto-scaling as a compound modifier. Instead, use scaling (for example, scaling policy), or scalable (for example, scalable target or scalable, load-balanced environment).
|
||||
|
||||
## B
|
||||
|
||||
**below**
|
||||
|
||||
Use only for physical space or screen descriptions, such as “the outlet below the vent,” or “the button below the bar pane.”
|
||||
|
||||
For orientation within a document, use *following* or *later*.
|
||||
|
||||
**big data**
|
||||
|
||||
**Boolean**
|
||||
|
||||
Avoid using the name of a Boolean value at the beginning of a sentence or sentence fragment. In general, capitalize the word Boolean. For specific programming languages, follow the usage in that language.
|
||||
|
||||
OpenSearch style:
|
||||
|
||||
- You can use the Boolean functions with Boolean expressions or integer expressions.
|
||||
- IsTruncated(): A Boolean value that specifies whether the resolved target list is truncated.
|
||||
|
||||
**bottom**
|
||||
|
||||
Use only as a general screen reference, such as “scroll to the bottom of the page.” Don’t use for window, page, or pane references to features or controls. Rather, use *lower* instead. For example, you can use the following wording: “Choose the button on the lower left.”
|
||||
|
||||
**browse**
|
||||
|
||||
Use when referring to scanning information or browsing the web. Don’t use when describing how to navigate to a particular item on our site or a computer. Instead, use *see* or *navigate to*.
|
||||
|
||||
**build (n., v.)**
|
||||
|
||||
Use as a verb to refer to compiling and linking code. Use as a noun only to refer to a compiled version of a program (for example, *Use the current build of Amazon Linux 2*...) in a programming reference.
|
||||
|
||||
## C
|
||||
|
||||
**CA**
|
||||
|
||||
certificate authority
|
||||
|
||||
**certs, certificates**
|
||||
|
||||
Use _certificates_ on first mention. It’s OK to use _certs_ thereafter.
|
||||
|
||||
**CI/CD**
|
||||
|
||||
Use _continuous integration_ and _continuous delivery (CI/CD)_ or _continuous integration and delivery (CI/CD)_ on first mention.
|
||||
|
||||
**cluster**
|
||||
|
||||
A collection of one or more nodes.
|
||||
|
||||
**cluster manager**
|
||||
|
||||
A single node that writes requests for the cluster and makes changes to other nodes. Each cluster contains a single cluster manager.
|
||||
|
||||
**console**
|
||||
|
||||
A tool inside OpenSearch Dashboards used to interact with the OpenSearch REST API.
|
||||
|
||||
**Cross-Cluster Replication**
|
||||
|
||||
A plugin that replicates indexes, mappings, and metadata from one OpenSearch cluster to another. Follows an active-passive model where the follower index pulls data from a leader index.
|
||||
|
||||
**cyber**
|
||||
|
||||
Except when dictated by open standards, use as a prefix in a closed compound: don’t use spaces or hyphens between _cyber_ and the rest of the word.
|
||||
|
||||
## D
|
||||
|
||||
**data**
|
||||
|
||||
Use data is, not data are. Don’t use datas. Use pieces of data or equivalent to describe individual items within a set of data.
|
||||
|
||||
**data center**
|
||||
|
||||
**dataset**
|
||||
|
||||
**data store, datastore**
|
||||
|
||||
Two words when used generically, but one word when referring to the VMware product.
|
||||
|
||||
**data type**
|
||||
|
||||
**dates**
|
||||
|
||||
Use one of the following date formats:
|
||||
|
||||
- When a human-readable date format is preferred, spell out the date using the Month D, YYYY format (for example, _October 1, 2022_). Do not use an ordinal number for the day (use _1_, not _1st_). If the context is clear, you can omit the year on subsequent mention. If the specific day isn’t known, use the Month YYYY format (for example, _October 2022_).
|
||||
- When a numeric, lexicographically sortable date is required, use the YYYY-MM-DD format (for example, _2022-10-01_). Make sure to add a zero (0) in front of a single-digit month and day. This is the ISO 8601 standard date format. Make sure also that you use a hyphen (-) and avoid omitting the year. Doing so avoids the ambiguity that’s caused by the common, locally used formats of MM/DD and DD/MM.
|
||||
|
||||
**deny list**
|
||||
|
||||
Use to describe a list of items that aren’t allowed (blocked). Do not use _blacklist_.
|
||||
|
||||
**double-click**
|
||||
|
||||
Always hyphenated. Don’t use _double click_.
|
||||
|
||||
**dropdown list**
|
||||
|
||||
**due to**
|
||||
|
||||
Don’t use. Use _because of_ instead.
|
||||
|
||||
## E
|
||||
|
||||
**effect**
|
||||
|
||||
_Effect_ as a noun refers to something that’s caused by something else. _Effect_ as a verb means to bring about. Do not confuse with _affect_.
|
||||
|
||||
**e.g.**
|
||||
|
||||
Avoid. Use for example or such as instead.
|
||||
|
||||
**Elastic IP address**
|
||||
|
||||
**email**
|
||||
|
||||
Use as a singular noun or adjective to refer to the collective concept, and use _message_ or _mail_ for individual items. Use _send email_ as the verb form. Don’t use the plural form because it’s a collective noun.
|
||||
|
||||
**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.
|
||||
|
||||
**enter**
|
||||
|
||||
In general, use in preference to _type_ when a user adds text or other input (such as numbers or symbols).
|
||||
|
||||
**etc., et cetera**
|
||||
|
||||
Do not use.
|
||||
|
||||
Generally speaking, etc. and its equivalents (such as and more or and so on) aren’t necessary.
|
||||
|
||||
## F
|
||||
|
||||
**fail over (v.), failover (n.)**
|
||||
|
||||
**file name**
|
||||
|
||||
**frontend (n., adj.)**
|
||||
|
||||
Use frontend as an adjective and a noun. Do not use front end or front-end. Do not make frontend possessive except as part of a compound noun, such as frontend system.
|
||||
|
||||
## H
|
||||
|
||||
**hardcode**
|
||||
|
||||
**hard disk drive (HDD)**
|
||||
|
||||
**high availability (HA)**
|
||||
|
||||
**high performance computing (HPC)**
|
||||
|
||||
**hostname**
|
||||
|
||||
## I
|
||||
|
||||
**i.e.**
|
||||
|
||||
Do not use. Use _that_ is or _specifically_ instead.
|
||||
|
||||
**in, on**
|
||||
|
||||
Use _in Windows_ or _in Linux_ in reference to components of the OS or work in the OS. Use on Windows in reference to Windows applications. Examples:
|
||||
|
||||
- Use the Devices and Printers Control Panel in Windows to install a new printer.
|
||||
- In Windows, run the setup command.
|
||||
- Select an application that runs on Windows.
|
||||
|
||||
Run applications and instances _in the cloud_, but extend services to the cloud.
|
||||
|
||||
**index, indexes**
|
||||
|
||||
A collection of JSON documents.
|
||||
|
||||
**install in, on**
|
||||
|
||||
install in a folder, directory, or path; install on a disk, drive, or instance.
|
||||
|
||||
**IP address**
|
||||
|
||||
Don’t abbreviate as _IP only_.
|
||||
|
||||
**Internet**
|
||||
|
||||
## K
|
||||
|
||||
**k-NN**
|
||||
|
||||
Short for _k-nearest neighbors_, the k-NN plugin enables users to search for the k-nearest neighbors to a query point across an index of vectors.
|
||||
|
||||
## L
|
||||
|
||||
**launch, start**
|
||||
|
||||
You _start_ an application but _launch_ an instance, environment, or cluster.
|
||||
|
||||
**let**
|
||||
|
||||
Avoid using _let_ to refer to making something in a service or feature possible for the user. Instead, rewrite to focus on what’s important from the user’s point of view.
|
||||
|
||||
**leverage**
|
||||
|
||||
Replace with _use_.
|
||||
|
||||
**lifecycle**
|
||||
|
||||
One word in reference to software.
|
||||
|
||||
**like (prep.)**
|
||||
|
||||
OK to use to call out something for comparison.
|
||||
|
||||
As a general rule, if you can replace like with similar to, it’s OK to use like. But, if you can replace _like_ with _such as_, use _such as_.
|
||||
|
||||
**locate in, on**
|
||||
|
||||
Located _in_ (a folder, directory, path), located on a disk drive or instance.
|
||||
|
||||
**log in (v.), login (adj., n.)**
|
||||
|
||||
Use with technologies with interfaces that use this verb. Also note that you log in to an instance, not log into. Also use log out and logout.
|
||||
|
||||
**LogStash**
|
||||
|
||||
A light-weight, open-source, server-side data processing pipeline that allows you to collect data from a variety of sources, transform it on the fly, and send it to your desired destination.
|
||||
|
||||
**LTS**
|
||||
|
||||
Long-Term Support
|
||||
|
||||
**Lucene**
|
||||
|
||||
Apache Lucene™ is a high-performance, full-featured search engine library written entirely in Java. OpenSearch uses a modified version of Lucene as the basis for search operations within OpenSearch.
|
||||
|
||||
## M
|
||||
|
||||
**machine learning**
|
||||
|
||||
Write as two words (no hyphen) in all cases, including when used as an adjective before a noun. Abbreviate to ML after first use if appropriate.
|
||||
|
||||
**Machine Learning (ML) Commons**
|
||||
|
||||
A new plugin that makes it easy to develop new ML features. It allows engineers to leverage existing open-source ML algorithms and reduce the efforts to build them from scratch.
|
||||
|
||||
**may**
|
||||
|
||||
Avoid. Use _can_ or _might_ instead.
|
||||
|
||||
**must, shall, should**
|
||||
|
||||
_Must_ and _shall_ refer to requirements. If the reader doesn’t follow the instruction, something won’t work right.
|
||||
|
||||
_Should_ is used with recommendations. If the reader doesn’t follow the instruction, it might be harder or slower, but it’ll work.
|
||||
|
||||
## N
|
||||
|
||||
**navigate to**
|
||||
|
||||
Not navigate _in_.
|
||||
|
||||
**near real time (n.), near real-time (adj.) (NRT)**
|
||||
|
||||
Use _near real time_ as a noun; use near real-time as an adjective. Don’t add a hyphen between _near_ and _real time_ or _real-time_.
|
||||
|
||||
Spell out _near real time_ on first mention; _NRT_ can be used on subsequent mentions.
|
||||
|
||||
**node**
|
||||
|
||||
A server that stores your data and processes search requests with OpenSearch, usually as part of a cluster. Do not use _master node_ and avoid using _worker node_.
|
||||
|
||||
**non-production**
|
||||
|
||||
Hyphenate to make the term easier to scan and read.
|
||||
|
||||
## O
|
||||
|
||||
**onsite**
|
||||
|
||||
**OpenSearch**
|
||||
|
||||
OpenSearch is a community-driven, open-source search and analytics suite derived from Apache 2.0 licensed Elasticsearch 7.10.2 and Kibana 7.10.2. It consists of a search engine daemon, OpenSearch, and a visualization and user interface, OpenSearch Dashboards.
|
||||
|
||||
**OpenSearch Dashboards**
|
||||
|
||||
The default visualization tool for data in OpenSearch. On first appearance, use the full name. “Dashboards” may be used on subsequent appearances as long as it is defined on first appearance: “OpenSearch Dashboards (Dashboards).”
|
||||
|
||||
open source (n.), open-source (adj.)
|
||||
|
||||
Use _open source_ as a noun (for example, “The code used throughout this tutorial is open source and can be freely modified”). Use _open-source_ as an adjective _(open-source software)_.
|
||||
|
||||
**operating system**
|
||||
|
||||
When referencing operating systems in documentation, follow these guidelines:
|
||||
|
||||
- In general, if your docs or procedures apply to both Linux and macOS, you can also include Unix.
|
||||
- Unix and UNIX aren’t the same. UNIX is a trademarked name that’s owned by The Open Group. In most cases, you should use Unix.
|
||||
- When referring to the Mac operating system, use macOS. Don’t say Mac, Mac OS, or OS X.
|
||||
- When referring to Windows, it’s not necessary to prefix with Microsoft.
|
||||
- If you need to reference multiple Unix-like operating systems, you should separate by commas and use the following order: Linux, macOS, or Unix.
|
||||
|
||||
**or earlier, or later**
|
||||
|
||||
OK to use with software versions.
|
||||
|
||||
## P
|
||||
|
||||
**Painless**
|
||||
|
||||
The default scripting language for OpenSearch, either used inline or stored for repeat use. Similar to Java’s language specification.
|
||||
|
||||
**per**
|
||||
|
||||
- Do not use to mean _according to_ (for example, per the agreement).
|
||||
- OK to use in meaning of _to_, _in_, _for_, or _by each_ (one per account) where space is limited and in set terms and phrases, such as any of the following:
|
||||
- queries per second (QPS)
|
||||
- bits per second (bps)
|
||||
- megabytes per second (MBps)
|
||||
- Consider writing around _per_ elsewhere. _Per_ can sound stuffy and confusing to some global users.
|
||||
|
||||
**percent**
|
||||
|
||||
Spell out (for example, 30 percent).
|
||||
|
||||
Exceptions: Use % in headlines, quotations, art callouts, and tables.
|
||||
|
||||
**Performance Analyzer**
|
||||
|
||||
An agent and REST API that allows you to query numerous performance metrics for your cluster, including aggregations of those metrics, independent of the Java Virtual Machine (JVM).
|
||||
|
||||
**please**
|
||||
|
||||
Avoid using except in quoted text.
|
||||
|
||||
**plugin**
|
||||
|
||||
Tools inside of OpenSearch that can be customized to enhance OpenSearch’s functionality. For a list of core plugins, see the [OpenSearch plugin installation]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/) page. Capitalize if it appears as part of the product name in the UI.
|
||||
|
||||
**pop-up**
|
||||
|
||||
**premise, premises**
|
||||
|
||||
With reference to property and buildings, always form as plural.
|
||||
|
||||
Correct: an on-premises solution
|
||||
|
||||
Incorrect: an on-premise solution, an on-prem solution
|
||||
|
||||
**primary shard**
|
||||
|
||||
A Lucene instance that contains data for some or all of an index.
|
||||
|
||||
### Q
|
||||
|
||||
**query**
|
||||
|
||||
A call used to request information about your data.
|
||||
|
||||
### R
|
||||
|
||||
**real time (n.) real-time (adj.)**
|
||||
|
||||
Use with caution; this term can imply a degree of responsiveness or speed that may not be true. When needed, use _real time_ as a noun (for example “The request is sent in real time”). Use _real-time_ as an adjective (“A real-time feed is displayed...”).
|
||||
|
||||
**replica shard**
|
||||
|
||||
Copy of a primary shard. Helps improve performance when using indexes across multiple nodes.
|
||||
|
||||
**repo**
|
||||
|
||||
Use as a synonym for repository, on second and subsequent use.
|
||||
|
||||
**RPM Package Manager (RPM)**
|
||||
|
||||
Formerly known as RedHat Package Manager. An open-source package management system for use with Linux distributions.
|
||||
|
||||
**rule**
|
||||
|
||||
A set of conditions, internals, and actions that create notifications.
|
||||
|
||||
## S
|
||||
|
||||
**screenshot**
|
||||
|
||||
**set up (v.), setup (n., adj.)**
|
||||
|
||||
Use _set up_ as a verb (“To set up a new user...”). Use _setup_ as a noun or adjective (“To begin setup...”).
|
||||
|
||||
**shard**
|
||||
|
||||
A piece of an index that consumes CPU and memory. Operates as a full Lucene index.
|
||||
|
||||
**since**
|
||||
|
||||
Use only to describe time events. Don’t use in place of because.
|
||||
|
||||
**solid state drive (SSD)**
|
||||
|
||||
**standalone**
|
||||
|
||||
**start, launch**
|
||||
|
||||
You _start_ an application but _launch_ an instance, environment, or cluster.
|
||||
|
||||
**startup (n.), start up (v.)**
|
||||
|
||||
Never hyphenated. Use _startup_ as a noun (for example, “The following startup procedure guides you through...”). Use _start up_ as a verb (“You can start up the instances by...”).
|
||||
|
||||
**SGD**
|
||||
|
||||
Stochastic Gradient Descent
|
||||
|
||||
## T
|
||||
|
||||
**time out (verb), timeout (noun, adjective)**
|
||||
|
||||
Never hyphenate. Use _time out_ as a verb (“The request will time out if the server doesn’t respond”). Use _timeout_ as a noun or adjective (“You can set the timeout interval by entering a number into...”).
|
||||
|
||||
**time frame**
|
||||
|
||||
**timestamp**
|
||||
|
||||
**time zone**
|
||||
|
||||
### U
|
||||
|
||||
**UltraWarm**
|
||||
|
||||
A storage tier that you can use to store and analyze your data with Elasticsearch and Kibana that is optimized for performance. To learn more about the service, see the introductory [blog post](https://aws.amazon.com/about-aws/whats-new/2020/05/aws-announces-amazon-elasticsearch-service-ultrawarm-general-availability/).
|
||||
|
||||
**US**
|
||||
|
||||
No periods, as specified in the Chicago Manual of Style.
|
||||
|
||||
**user**
|
||||
|
||||
In most cases, replace with the more direct form you. Reserve _user_ for cases where you are referring to a third party (not the audience you are writing for).
|
||||
|
||||
## V
|
||||
|
||||
**v., vs., versus**
|
||||
|
||||
Do not use. Use _compared_ to or _compared with_ instead.
|
||||
|
||||
**via**
|
||||
|
||||
Do not use. Replace with by using, through, or with or a more specific phrase such as by accessing or by choosing.
|
||||
|
||||
## W
|
||||
|
||||
**web**
|
||||
|
||||
**webpage**
|
||||
|
||||
Never _web page_.
|
||||
|
||||
**website**
|
||||
|
||||
Never _web site_.
|
||||
|
||||
**while, although, whereas**
|
||||
|
||||
Only use _while_ to mean “during an interval of time.” Don’t use it to mean although because it is often ambiguous. _Whereas_ is a better alternative to although in many cases, but it can sound overly formal.
|
||||
|
||||
**wish, want, desire, need**
|
||||
|
||||
_Wish_ and _desire_ are indirect and nuanced versions of _want_. Don’t use them. Be direct.
|
||||
|
||||
Do not confuse wants with needs. Use the term that’s appropriate to the situation. _Need_ connotes a requirement or obligation, whereas _want_ indicates that you have an intent but still a choice of valid actions.
|
||||
|
||||
## Y
|
||||
|
||||
**Yellowdog Updater Modified (YUM)**
|
||||
|
||||
An open-source tool for command-line and graphical-based package management for RPM (RedHat Package Manager)-based Linux systems.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
Loading…
Reference in New Issue