Summary
Grafana's style guide and Vale rules already handle several inclusive language substitutions (for example, whitelist to allowlist, blacklist to blocklist, kill to stop/exit/cancel). This proposal extends that approach to cover phrases that normalize violence toward animals, replacing them with clearer, more professional technical alternatives.
This was initially raised in grafana/grafana#105177, where a maintainer directed us to this repository as the right place for Vale rule changes.
Proposed substitutions
These are common phrases in technical documentation that have clearer, more precise alternatives:
| Current phrase |
Suggested alternative |
Rationale |
canary deployment/release |
progressive rollout |
More descriptive of the actual deployment pattern |
cattle vs. pets |
ephemeral vs. persistent |
More precise technical terminology |
dogfooding |
internal testing, self-hosting |
Clearer description of the practice |
war room |
incident room, response room |
More professional, already common in incident management |
dead letter queue |
failed message queue, undeliverable message queue |
More descriptive of actual function |
dead code |
unused code, unreachable code |
More technically precise |
killed/kill a process |
Already handled (stop/exit/cancel/end) |
N/A |
Implementation options
Option A: Add to existing WordList.yml
The simplest approach would be to add relevant substitutions directly to the existing Grafana/WordList.yml, consistent with how whitelist/blacklist and kill/terminate/abort are already handled.
Option B: Reference an external Vale package
There is an open-source Vale package specifically for this purpose: Open-Paws/vale-no-animal-violence. It could be added as a package in .vale.ini, similar to how the Hugo package is referenced. This keeps the rules maintained separately and available to other projects.
Option C: Cherry-pick relevant rules
Review the substitutions from the package above and add only those that are relevant to Grafana's documentation context.
Context
Several major style guides (including Microsoft's, Google's, and the Conscious Style Guide) recommend avoiding unnecessarily violent or animal-derived metaphors when clearer alternatives exist. Many of the alternatives proposed here are also more technically precise, which aligns with Grafana's existing commitment to clear, direct documentation language.
The full package and word list are available at: https://github.com/Open-Paws/vale-no-animal-violence
Happy to submit a PR with whichever approach works best for the team.
Summary
Grafana's style guide and Vale rules already handle several inclusive language substitutions (for example,
whitelisttoallowlist,blacklisttoblocklist,killtostop/exit/cancel). This proposal extends that approach to cover phrases that normalize violence toward animals, replacing them with clearer, more professional technical alternatives.This was initially raised in grafana/grafana#105177, where a maintainer directed us to this repository as the right place for Vale rule changes.
Proposed substitutions
These are common phrases in technical documentation that have clearer, more precise alternatives:
canary deployment/releaseprogressive rolloutcattle vs. petsephemeral vs. persistentdogfoodinginternal testing,self-hostingwar roomincident room,response roomdead letter queuefailed message queue,undeliverable message queuedead codeunused code,unreachable codekilled/kill a processstop/exit/cancel/end)Implementation options
Option A: Add to existing WordList.yml
The simplest approach would be to add relevant substitutions directly to the existing
Grafana/WordList.yml, consistent with howwhitelist/blacklistandkill/terminate/abortare already handled.Option B: Reference an external Vale package
There is an open-source Vale package specifically for this purpose: Open-Paws/vale-no-animal-violence. It could be added as a package in
.vale.ini, similar to how the Hugo package is referenced. This keeps the rules maintained separately and available to other projects.Option C: Cherry-pick relevant rules
Review the substitutions from the package above and add only those that are relevant to Grafana's documentation context.
Context
Several major style guides (including Microsoft's, Google's, and the Conscious Style Guide) recommend avoiding unnecessarily violent or animal-derived metaphors when clearer alternatives exist. Many of the alternatives proposed here are also more technically precise, which aligns with Grafana's existing commitment to clear, direct documentation language.
The full package and word list are available at: https://github.com/Open-Paws/vale-no-animal-violence
Happy to submit a PR with whichever approach works best for the team.