mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Docs: Add guidelines for inclusive language (#25533)
* 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>
This commit is contained in:
parent
7e8bd0c1b7
commit
0f41ca620b
@ -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.
|
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
|
## 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.
|
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.
|
||||||
@ -31,7 +57,7 @@ The following sections provide general guidelines on topics specific to Grafana
|
|||||||
* Write in present tense.
|
* Write in present tense.
|
||||||
- Not: The panel will open.
|
- Not: The panel will open.
|
||||||
- Use: The panel opens. Grafana opens the panel.
|
- 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.
|
- **Exceptions:** If an ampersand is used in the Grafana UI, then match the UI.
|
||||||
* Avoid using internal slang and jargon in technical documentation.
|
* Avoid using internal slang and jargon in technical documentation.
|
||||||
|
|
||||||
@ -156,7 +182,7 @@ One word, not two.
|
|||||||
|
|
||||||
#### open source, open-source
|
#### 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._
|
Do not hyphenate when it is used as a noun. For example: _Open source is the best way to develop software._
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user