From b02dec82114fa5cea0cd7042239148d0f9b81d8f Mon Sep 17 00:00:00 2001 From: Nathan Bower Date: Thu, 10 Aug 2023 10:29:16 -0400 Subject: [PATCH] Add style guidelines and terms (#4734) * Add style guidelines and terms Signed-off-by: natebower <102320899+natebower@users.noreply.github.com> * Reviewer feedback Signed-off-by: natebower <102320899+natebower@users.noreply.github.com> --------- Signed-off-by: natebower <102320899+natebower@users.noreply.github.com> --- STYLE_GUIDE.md | 6 ++++-- TERMS.md | 10 +++++++++- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index af3df8cf8d..bdc167dbbb 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -19,7 +19,7 @@ The following naming conventions should be observed in OpenSearch Project conten * OpenSearch Dashboards is the UI for OpenSearch. On first appearance, use the full name *OpenSearch Dashboards*. *Dashboards* can be used for subsequent appearances. * *Security Analytics* is a security information and event management (SIEM) solution for OpenSearch. Capitalize both words when referring to the name of the solution. * Observability is collection of plugins and applications that let you visualize data-driven events by using Piped Processing Language (PPL). Capitalize *Observability* when referring to the name of the solution. -* Refer to OpenSearch Project customers as *users*, and refer to the larger group of users as *the community*. +* Refer to OpenSearch Project customers as *users*, and refer to the larger group of users as *the community*. Do not refer to the OpenSearch Project or to the AWS personnel working on the project as a *team*, as this implies differentiation within the community. #### Product names @@ -65,7 +65,7 @@ The voice of the OpenSearch Project is people oriented and focused on empowering 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. +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. Do not refer to the OpenSearch Project or to the AWS personnel working on the project as a *team*, as this implies differentiation within the community. 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. @@ -325,6 +325,8 @@ We follow a slightly modified version of the _Microsoft Writing Style Guide_ gui ### Punctuation and capitalization +- Use only one space after a period. + - 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 sentence case for titles, headings, and table headers. Titles of standalone documents may use title case. diff --git a/TERMS.md b/TERMS.md index 7855d8cd64..02df1fcf46 100644 --- a/TERMS.md +++ b/TERMS.md @@ -168,6 +168,10 @@ A collection of one or more nodes. A single node that routes requests for the cluster and makes changes to other nodes. Each cluster contains a single cluster manager. +**command line, command-line** + +Two words as a noun. Hyphenate as an adjective. + **console** A tool inside OpenSearch Dashboards used to interact with the OpenSearch REST API. @@ -509,12 +513,16 @@ OpenSearch is a community-driven, open-source search and analytics suite derived **OpenSearch Dashboards** -The default visualization tool for data in OpenSearch. On first appearance, use the full name. “Dashboards” may be used on subsequent appearances. +The default visualization tool for data in OpenSearch. On first appearance, use the full name. *Dashboards* may be used on subsequent appearances. 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)_. +**OpenSearch Playground** + +OpenSearch Playground provides a central location for existing and evaluating users to explore features in OpenSearch and OpenSearch Dashboards without downloading or installing any OpenSearch components locally. + **operating system** When referencing operating systems in documentation, follow these guidelines: