iSharkFly-Docs
/
opensearch-docs-cn
mirror of https://github.com/iSharkFly-Docs/opensearch-docs-cn
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updates-style-guide (#1974) 

* Updates-style-guide

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

* Review edits

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:
Nate Bower 2022-11-18 10:21:43 -05:00 committed by GitHub
parent f055d7d2d0
commit e95ccd419f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 94 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
STYLE_GUIDE.md
View File

@ -56,13 +56,87 @@ Avoid excessive words, such as please. Be courteous but not wordy. Extra detail
The following guidelines should be observed in OpenSearch Project content.
### Acronyms
Spell out acronyms the first time that you use them on a page and follow them with the acronym in parentheses. Use the format `spelled-out term (acronym)`. On subsequent use, use the acronym alone.
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.
In general, spell out acronyms once on a page. However, you can spell them out more often for clarity.
Make an acronym plural by adding an *s* to the end of it. Do not add an apostrophe.
How an acronym is pronounced determines whether you use the article *an* or *a* before it. If it's pronounced with an initial vowel sound, use *an*. Otherwise, use *a*.
If the first use of an acronym is in a heading, retain the acronym in the heading, and then write out the term in the following body text, followed by the acronym in parentheses. Don't spell out the term in the heading with the acronym included in parentheses. If the first use of the service name is in a title or heading, use the short form of the name in the heading, and then use the long form followed by the short form in parentheses in the following body text.
In general, spell out abbreviations that end with *-bit* or *-byte*. Use abbreviations only with numbers in specific measurements. Always include a space between the number and unit. Abbreviations that are well known and don't need to be spelled out are *KB*, *MB*, *GB*, and *TB*.
Some acronyms are better known than their spelled-out counterparts or might be used almost exclusively. These include industry standard protocols, markdown and programming languages, and common file formats. You don't need to spell out these acronyms.
The following table lists acronyms that you don't need to spell out.
| Acronym | Spelled-out term |
| :--------- | :------- |
| 3D | three-dimensional |
| API | application programming interface |
| ASCII | American Standard Code for Information Interchange |
| BASIC | Beginner's All-Purpose Symbolic Instruction Code |
| CPU | central processing unit |
| DOS | disk operating system |
| FAQ | frequently asked questions |
| FTP | File Transfer Protocol |
| GIF | Graphics Interchange Format |
| HTML | hypertext markup language |
| HTTP | hypertext transfer protocol |
| HTTPS | hypertext transfer protocol secure |
| HTTP(s) | Use to refer to both protocols, HTTP and HTTPS. |
| I/O | input/output |
| ID | identifier |
| IP | Internet protocol |
| JPEG | Joint Photographic Experts Group |
| JSON | JavaScript Object Notation |
| NAT | network address translation |
| NGINX | engine x |
| PDF | Portable Document Format |
| RAM | random access memory |
| REST | Representational State Transfer |
| RGB | red-green-blue |
| ROM | read-only memory |
| SAML | Security Assertion Markup Language |
| SDK | software development kit |
| SSL | Secure Sockets Layer |
| TCP | Transmission Control Protocol |
| TIFF | Tagged Image File Format |
| TLS | Transport Layer Security |
| UI | user interface |
| URI | uniform resource identifier |
| URL | uniform resource locator |
| UTC | Coordinated Universal Time |
| UTF | Unicode Transformation Format |
| XML | Extensible Markup Language |
| YAML | YAML Ain't Markup Language |
### Links
- **Formal cross-references**: In most cases, a formal cross-reference (the title of the page you're linking to) is the preferred style because it provides context and helps readers understand where they're going when they choose the link. Follow these guidelines for formal cross-references:
- Introduce links with formal introductory text:
- Use "For information *about*" or "For more information *about*." Don't use "For information *on*."
- If you are linking to procedures, you can use either "For instructions *on*" or "instructions *for*." Don't use "instructions *about*."
- Where space is limited (for example, in a table), you can use "*See* [link text]." Don't use *go to*.
- Ensure that the link text matches the section title text. <br> <br> Example: "To get involved, see [Contributing](https://opensearch.org/source.html) on the OpenSearch website." <br> <br>
- **Embedded links**: Embedded links are woven into a sentence without formal introductory text. They're especially useful in tables or other elements where space is tight. The text around the embedded link must relate to the information in the link so that the reader understands the context. Do not use *here* or *click here* for link text because it creates accessibility problems. <br> <br> Example: "Finally, [delete the index](https://opensearch.org/docs/latest/api-reference/index-apis/delete-index)."
### Punctuation and capitalization
- Use sentence case for titles, headings, and table headers. Titles of standalone documents may use title case.
- 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.
- 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 or image, 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).
@ -76,8 +150,6 @@ The following guidelines should be observed in OpenSearch Project content.
- 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.
@ -104,12 +176,6 @@ The following guidelines should be observed in OpenSearch Project content.
### Formatting and organization
- Links: In most cases, a formal cross-reference (the title of the page you're linking to) is the preferred style because it provides context and helps readers understand where they're going when they choose the link. Follow these guidelines for formal cross-references:
- Introduce links with formal introductory text:
- Use "For information *about*" or "For more information *about*." Don't use "For information *on*."
- If you are linking to procedures, you can use either "For instructions *on*" or "instructions *for*." Don't use "instructions *about*."
- Where space is limited (for example, in a table), you can use "*See* [link text]." Don't use "*go to*".
- You can refer to APIs in three ways:
1. When referring to API names, capitalize all words in the name (example: "Field Capabilities API").
2. When referring to API operations by the exact name of the endpoint, use lowercase with code format (example: "`_field_caps` API").
@ -183,10 +249,6 @@ Following is an example of procedure phrasing and formatting from Amazon EC2.
- 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.
- If the first use of an acronym is in a heading, retain the acronym in the heading, and then write out the term in the following body text, followed by the acronym in parentheses. Don't spell out the term in the heading with the acronym included in parentheses.
- 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

22
TERMS.md
View File

@ -8,6 +8,12 @@ This is how we use our terms, but we’re always open to hearing your suggestion
Do not use because it has unpleasant associations and is unnecessarily harsh sounding. Use *stop*, *end*, or *cancel* instead.
**above**
Use only for physical space or screen descriptions, for example, "the outlet above the floor" or "the button above the bar pane."
For orientation within a document use *previous*, *preceding*, or *earlier*.
**ad hoc**
Avoid. Use *one-time* instead.
@ -367,6 +373,10 @@ Use with technologies with interfaces that use this verb. Also note that you log
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.
**lower left, lower right**
Hyphenate as adjectives. Use instead of *bottom left* and *bottom right*, unless the field name uses *bottom*. For example, "The lower-right corner."
**LTS**
Long-Term Support
@ -470,9 +480,9 @@ The default scripting language for OpenSearch, either used inline or stored for
**percent**
Spell out (for example, 30 percent).
Spell out in blog posts (for example, 30 percent).
Exceptions: Use % in headlines, quotations, art callouts, and tables.
Use % in headlines, quotations, and tables or in technical copy.
**Performance Analyzer**
@ -608,6 +618,10 @@ Avoid using as a verb to refer to an action that precipitates a subsequent actio
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/).
**upper left, upper right**
Hyphenate as adjectives. Use instead of *top left* and *top right*, unless the field name uses *top*. For example, "The upper-right corner."
**US**
No periods, as specified in the Chicago Manual of Style.
@ -618,7 +632,9 @@ In most cases, replace with the more direct form you. Reserve _user_ for cases w
**username**
## V
## V
**version**
**v., vs., versus**