From the editor's desk: OpenSearch Project voice and tone
In the first installment of our From the editor’s desk series, we focused on the OpenSearch Project and inclusion, a subject that is foundational to who we are and how we talk to each other as a community. For the second installment, we’d like to focus on another subject related to community interaction: voice and tone.
In response to feedback received during OpenSearchCon 2022, we have updated our guidance on voice and tone. We have also added new guidance on OpenSearch Project naming conventions and brand personality traits. Check out this new and updated guidance in the OpenSearch Project style guidelines.
Here is a summary of what has changed.
Naming conventions
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 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 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.
Tone
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 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. Use humor with caution because it is subjective, can be easily misunderstood, and can potentially alienate your audience.
Brand personality traits
| 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. 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. - Be specific. Avoid estimates or general claims when exact data can be provided. - Support claims with data. If something is “faster” or “more accurate,” say how much. - 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. - Be forthcoming. Communicate time-sensitive news and information in a thorough and timely manner. - 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. - Invite discussion and feedback. We have several mechanisms for open discussion, including requests for comment (RFCs), a community forum, and community meetings. |
| 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. 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. - Do not exaggerate or overstate. Let the facts and results speak for themselves. - Encourage the audience to explore our products for themselves. Offer guidance to help them do so. - 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. - 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. - 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. 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. 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. - Avoid sensitive terms. - Don’t use offensive terms. - Don’t use ableist or sexist language or language that perpetuates racist structures or stereotypes. - 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. - Images: - Add introductory text that provides sufficient context for each image. - Add ALT text that describes the image for screen readers. - Procedures: Not everyone uses a mouse, so use device-independent verbs; for example, use “choose” instead of “click.” - 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.” |
Join the conversation
As always, the OpenSearch Project team is committed to promoting a community where everyone can join and contribute, and we welcome community contributions to the OpenSearch style guidelines. To access our documentation, see the OpenSearch documentation home page. If you want to contribute to the OpenSearch documentation, see the CONTRIBUTING.md file, which covers how to open an issue or create a pull request on GitHub.
Thank you for contributing to the OpenSearch Project and helping us to raise the bar on quality!
