Skip to content

Commit

Permalink
Add style guidelines and terms (#4734)
Browse files Browse the repository at this point in the history
* 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>
  • Loading branch information
natebower authored Aug 10, 2023
1 parent 4d6106a commit b02dec8
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 3 deletions.
6 changes: 4 additions & 2 deletions STYLE_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down
10 changes: 9 additions & 1 deletion TERMS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down

0 comments on commit b02dec8

Please sign in to comment.