diff --git a/contribute/style-guides/documentation-style-guide.md b/contribute/style-guides/documentation-style-guide.md index 82541a2fee3..e053c729112 100644 --- a/contribute/style-guides/documentation-style-guide.md +++ b/contribute/style-guides/documentation-style-guide.md @@ -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. @@ -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. @@ -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._