Skip to content

Commit

Permalink
Docs: Add guidelines for inclusive language (grafana#25533)
Browse files Browse the repository at this point in the history
* Docs: Add guidelines for inclusive language

* Fix review comments

* Fix review comments

* Update documentation-style-guide.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>
  • Loading branch information
marcusolsson and oddlittlebird authored Jul 6, 2020
1 parent 7e8bd0c commit 0f41ca6
Showing 1 changed file with 28 additions and 2 deletions.
30 changes: 28 additions & 2 deletions contribute/style-guides/documentation-style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,32 @@ For all items not covered in this guide, refer to the [Microsoft Style Guide](ht

The [codespell](https://github.com/codespell-project/codespell) tool is run for every change to catch common misspellings.

## Inclusive language

This section provides guidelines on how to avoid using charged language in documentation.

### Allowing and blocking

Don't use "whitelist" or "blacklist" when referring to allowing or blocking content or traffic.

* When used as a noun, use "allowlist" or "blocklist".
* When used as a verb, use "allow" or "block"

Example: _To **allow** outgoing traffic, add the IP to the **allowlist**._

### Leader and follower

Don't use "master" or "slave" to describe relationships between nodes or processes.

* Use "leader", "main" or "primary," instead of "master."
* Use "follower" or "secondary," instead of "slave."

### Exceptions

When referring to a configuration or settings used by third-party libraries och technologies outside the Grafana project, prefer the original name to avoid confusion.

For example, use "master" when referring to the default Git branch.

## Grafana-specific style

The following sections provide general guidelines on topics specific to Grafana documentation. Note that for the most part, these are *guidelines*, not rigid rules. If you have questions, ask in the #docs channel of Grafana Slack.
Expand All @@ -31,7 +57,7 @@ The following sections provide general guidelines on topics specific to Grafana
* Write in present tense.
- Not: The panel will open.
- Use: The panel opens. Grafana opens the panel.
* Do not use an ampersand (&) as an abbreviation for "and."
* Do not use an ampersand (&) as an abbreviation for "and."
- **Exceptions:** If an ampersand is used in the Grafana UI, then match the UI.
* Avoid using internal slang and jargon in technical documentation.

Expand Down Expand Up @@ -156,7 +182,7 @@ One word, not two.

#### open source, open-source

Do not hyphenate when used as an adjective unless the lack of hyphen would cause confusion. For example: _Open source software design is the most open open-source system I can imagine._
Do not hyphenate when used as an adjective unless the lack of hyphen would cause confusion. For example: _Open source software design is the most open open-source system I can imagine._

Do not hyphenate when it is used as a noun. For example: _Open source is the best way to develop software._

Expand Down

0 comments on commit 0f41ca6

Please sign in to comment.