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.md (#1602) 

* Updates STYLE_GUIDE.md

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

* Adjusts table

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

* Adds managed service definition

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

* Edits to bulleted list

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

* Edit one word

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-10-18 16:53:59 -04:00 committed by GitHub
parent e74dd24525
commit 8461daf22b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 37 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
STYLE_GUIDE.md
View File

@ -1,52 +1,60 @@
# 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.
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
## Naming conventions, voice, tone, and brand personality traits
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.
The following sections provide guidance on OpenSearch Project naming conventions, voice, tone, and brand personality traits.
### Voice
### Naming conventions
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.
The following naming conventions should be observed in OpenSearch Project content:
* Capitalize both words when referring to the *OpenSearch Project*. The OpenSearch Project has three products: OpenSearch, OpenSearch Dashboards, and Data Prepper.
* *OpenSearch* is the name for the distributed search and analytics engine used by Amazon OpenSearch Service.
* Amazon OpenSearch Service is a managed service that makes it easy to deploy, operate, and scale OpenSearch. Use the full name *Amazon OpenSearch Service* on first appearance. The abbreviated service name, *OpenSearch Service*, can be used for subsequent appearances.
* OpenSearch Dashboards is the UI for OpenSearch. On first appearance, use the full name *OpenSearch Dashboards*. *Dashboards* can be used for subsequent appearances.
* Refer to OpenSearch Project customers as *users*, and refer to the larger group of users as *the community* or *the OpenSearch community*.
### 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 Project identity and brand.
#### Voice
The voice of the OpenSearch Project is people oriented and focused on empowering the user directly. We use language that emphasizes what the user can do with OpenSearch rather than what tasks OpenSearch 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.
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.
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.
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
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
#### 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.
The tone of the OpenSearch Project is conversational, welcoming, engaging, and open. The overall tone is knowledgeable but humble, informal but authoritative, informative but not dry, and friendly without being overly familiar.
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.
We talk to readers in their own words, never assuming that they understand how OpenSearch 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.
Avoid excessive words, such as please. Be courteous but not wordy. Extra detail can often be moved elsewhere.
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.
Use humor with caution because it is subjective, can be easily misunderstood, and can potentially alienate your audience.
### Brand personality traits
As you write content, apply the following tone traits.
| **Trait** | **What it is** | **What it isn't** |
|---|---|---|
| **Approachable** | Personable, Friendly, Welcoming, Genuine | Chatty, Hyperbolic, Cloying, Insincere |
| **Authoritative** | Professional, Expert, Informed, Dependable, Validated | Stuffy, Dictatorial, Smug, Unsure, Untested |
| **Concise** | Succinct, Brief, Lean, To the point | Wordy, Lengthy, Verbose, Rambling |
| **Conversational** | Informal, Casual, Familiar, Matter-of-fact | Stilted, Pompous, Chummy, Pedantic |
| **Directed** | Focused, Guided, Controlled, Purposeful, Predictable, Definitive, Essential | Vague, Wandering, Confusing, Ambiguous, Surprising, Indecisive, Redundant |
| **Respectful** | Considerate, Helpful, Supportive, Empathic | Insulting, Condescending, Insensitive, Indifferent |
| **Simple** | Plain, Everyday, Recognizable, Clear, Straightforward, Common | Fancy, Esoteric, Perplexing, Unintelligible, Complicated, Unusual |
| **Smart** | Knowledgeable, Logical, Correct, Consistent, Coherent, Grammatical, Polished | Pedantic, Invalid, Inaccurate, Varying, Disorganized, Careless, Sloppy |
| **Trustworthy** | Reliable, Truthful, Fair, Candid | Infallible, Evasive, Devious, Obfuscating |
| Personality trait | Description | Guidance |
| :--------- | :------- | :------ |
| **Clear and precise** | The OpenSearch Project understands that our community works, develops, and builds in roles and organizations that require precise thinking and thorough documentation. We strive to use precise language—to clearly say what we mean without leaving ideas open to interpretation, to support our assertions with facts and figures, and to provide credible and current (third-party) references where called for. <br> <br> We communicate in plain, direct language that is easily understood. Complex concepts are introduced in a concise, unambiguous way that does not assume knowledge on the part of the reader. High-level content is supported by links to more in-depth or technical content that users can engage with at their convenience. | - Write with clarity and choose words carefully. Think about the audience and how they might interpret your assertions. <br> - Be specific. Avoid estimates or general claims when exact data can be provided. <br> - Support claims with data. If something is “faster” or “more accurate,” say how much. <br> - When citing third-party references, include direct links. |
| **Transparent and open** | As an open-source project, we exchange information with the community in an accessible and transparent manner. We publish our product plans in the open on GitHub, share relevant and timely information related to the project through our forum and/or our blog, and engage in open dialogues related to product and feature development in the public sphere. Anyone can view our roadmap, raise a question or an issue, or participate in our community meetings. | - Tell a complete story. If you’re walking the reader through a solution or sharing news, don’t skip important information. <br> - Be forthcoming. Communicate time-sensitive news and information in a thorough and timely manner. <br> - If there’s something the reader needs to know, say it up front. Don’t “bury the lede.” |
| **Collaborative and supportive** | We’re part of a community that is here to help. We aim to be resourceful on behalf of the community and encourage others to do the same. To facilitate an open exchange of ideas, we provide forums through which the community can ask and answer one another’s questions. | - Use conversational language that welcomes and engages the audience. Have a dialogue. <br> - Invite discussion and feedback. We have several mechanisms for open discussion, including requests for comment (RFCs), a [community forum](https://forum.opensearch.org/), and [community meetings](https://www.meetup.com/OpenSearch/).
| **Trustworthy and personable** | We stay grounded in the facts and the data. We do not overstate what our products are capable of. We demonstrate our knowledge in a humble but authoritative way and reliably deliver what we promise. We provide mechanisms and support that allow the audience to explore our products for themselves, demonstrating that our actions consistently match our words. <br> <br> We speak to the community in a friendly, welcoming, judgment-free way so that our audience perceives us as being approachable. Our content is people oriented and focused on empowering the user directly. | - Claims and assertions should be grounded in facts and data and supported accordingly. <br> - Do not exaggerate or overstate. Let the facts and results speak for themselves. <br> - Encourage the audience to explore our products for themselves. Offer guidance to help them do so. <br> - Write directly and conversationally. Have a dialogue with your audience. Imagine writing as if you’re speaking directly to the person for whom you’re creating content. <br> - Write from the community, for the community. Anyone creating or consuming content about OpenSearch is a member of the same group, with shared interest in learning about and building better search and analytics solutions. <br> - Use judgment-free language. Words like simple, easy, and just create a skill judgment that may not apply to everyone in the OpenSearch community. |
| **Inclusive and accessible** | As an open-source project, The OpenSearch Project is for everyone, and we are inclusive. We value the diversity of backgrounds and perspectives in the OpenSearch community and welcome feedback from any contributor, regardless of their experience level. <br> <br> We design and create content so that people with disabilities can perceive, navigate, and interact with it. This ensures that our documentation is available and useful for everyone and helps improve the general usability of content. <br> <br> We understand our community is international and our writing takes that into account. We use plain language that avoids idioms and metaphors that may not be clear to the broader community. | - Use inclusive language to connect with the diverse and global OpenSearch Project audience.- Be careful with our word choices. <br> - Avoid [sensitive terms](https://github.com/opensearch-project/documentation-website/blob/main/STYLE_GUIDE.md#sensitive-terms). <br> - Don't use [offensive terms](https://github.com/opensearch-project/documentation-website/blob/main/STYLE_GUIDE.md#offensive-terms). <br> - Don't use ableist or sexist language or language that perpetuates racist structures or stereotypes. <br> - Links: Use link text that adequately describes the target page. For example, use the title of the target page instead of “here” or “this link.” 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. <br> - Images: <br> &nbsp;&nbsp;- Add introductory text that provides sufficient context for each image. <br> &nbsp;&nbsp;- Add ALT text that describes the image for screen readers. <br> - Procedures: Not everyone uses a mouse, so use device-independent verbs; for example, use “choose” instead of “click.” <br> - Location: When you’re describing the location of something else in your content, such as an image or another section, use words such as “preceding,” “previous,” or “following” instead of “above” and “below.”
## Style guidelines
The following guidelines should be observed in OpenSearch content.
The following guidelines should be observed in OpenSearch Project content.
### Punctuation and capitalization
@ -205,13 +213,13 @@ All posts should contain one or more calls to action that give readers the oppor
## Inclusive content
When developing OpenSearch documentation, we strive to create content that is inclusive and free of bias. We use inclusive language to connect with the diverse and global OpenSearch audience, and we are careful in our word choices. Inclusive and bias-free content improves clarity and accessibility of our content for all audiences, so we avoid ableist and sexist language and language that perpetuates racist structures or stereotypes. In practical terms, this means that we do not allow certain terms to appear in our content, and we avoid using others, *depending on the context*.
When developing OpenSearch Project documentation, we strive to create content that is inclusive and free of bias. We use inclusive language to connect with the diverse and global OpenSearch Project audience, and we are careful in our word choices. Inclusive and bias-free content improves clarity and accessibility of our content for all audiences, so we avoid ableist and sexist language and language that perpetuates racist structures or stereotypes. In practical terms, this means that we do not allow certain terms to appear in our content, and we avoid using others, *depending on the context*.
Our philosophy is that we positively impact users and our industry as we proactively reduce our use of terms that are problematic in some contexts. Instead, we use more technically precise language and terms that are inclusive of all audiences.
### Offensive terms
The following terms may be associated with unconscious racial bias, violence, or politically sensitive topics and should not appear in OpenSearch content, if possible. Note that many of these terms are still present but on a path to not being supported. For example, `slave` was removed from the Python programming language in 2018, and the open-source community continues to work toward replacing these terms.
The following terms may be associated with unconscious racial bias, violence, or politically sensitive topics and should not appear in OpenSearch Project content, if possible. Note that many of these terms are still present but on a path to not being supported. For example, `slave` was removed from the Python programming language in 2018, and the open-source community continues to work toward replacing these terms.
| Don’t use | Guidance/Use instead |
|----------------|-----------------------------|