docs: add animal idiom alternatives to inclusive language guide#43256
docs: add animal idiom alternatives to inclusive language guide#43256chrisdavidmills merged 4 commits intomdn:mainfrom
Conversation
Add guidance to avoid figurative idioms that use animals in violent or harmful contexts, with plain-English alternatives for three common phrases: "kill two birds with one stone," "beating a dead horse," and "more than one way to skin a cat." Scope is intentionally narrow: technical terms like `kill` (Unix command), monkey-patching, and dogfooding are excluded per reviewer consensus in issue mdn#43242. Fixes mdn#43242
stuckvgn
requested review from
chrisdavidmills
and removed request for
a team
github-actions
bot
added
Content:Meta
| - **Sanity** should be replaced with **coherence**. | ||
| - Instead of **dummy**, use **placeholder**. | ||
| - You should not need to use the terms **crazy** and **insane** in documentation; however, if the case arises, consider using **fantastic** instead. | ||
| - Avoid figurative idioms that use animals in violent or harmful contexts. For example: |
There was a problem hiding this comment.
"Animal" is not the concern here.
| - Avoid figurative idioms that use animals in violent or harmful contexts. For example: | |
| - Avoid terms that have implications of violence. For example: |
There was a problem hiding this comment.
I would argue that "animals" are absolutely a concern, but so is every other living thing. For example, I have strong environmental views and regard things like deforestation as equally upsetting.
So how about something that takes this into account, but more strongly implies cruelty to animals (and other living beings):
| - Avoid figurative idioms that use animals in violent or harmful contexts. For example: | |
| - Avoid figurative idioms that imply violence or cruelty. For example: |
There was a problem hiding this comment.
Fair point — the concern is broader than just animals. I've adopted @chrisdavidmills' suggested wording: "Avoid figurative idioms that imply violence or cruelty." That captures it without being unnecessarily narrow.
There was a problem hiding this comment.
Applied — "imply violence or cruelty" is better framing. Thanks for finding the middle ground here.
chrisdavidmills
left a comment
chrisdavidmills
left a comment
There was a problem hiding this comment.
@stuckvgn another small comment for you, but mostly looking good. Thanks for the contribution!
As a follow-up, do you want to search the site and look to replace any of these phrases that are already in use?
| - You should not need to use the terms **crazy** and **insane** in documentation; however, if the case arises, consider using **fantastic** instead. | ||
| - Avoid figurative idioms that use animals in violent or harmful contexts. For example: | ||
| - Instead of "kill two birds with one stone," use "solve two problems at once." | ||
| - Instead of "beating a dead horse," use "belaboring the point" or "going in circles." |
There was a problem hiding this comment.
| - Instead of "beating a dead horse," use "belaboring the point" or "going in circles." | |
| - Instead of "beating a dead horse," use "belaboring the point" or "going round in circles." |
Maybe? My gut is that this is slightly more common, although this could also be a US/UK English thing (I'm English).
There was a problem hiding this comment.
Good catch, updated to "going round in circles."
- Use "imply violence or cruelty" per chrisdavidmills' suggestion - Use "going round in circles" per chrisdavidmills' suggestion
|
Both suggestions applied — thanks @chrisdavidmills and @Josh-Cena. @chrisdavidmills re: the follow-up — yeah, happy to do a sweep for existing usage and open a separate PR for replacements. |
|
Preview URLs (1 page) (comment last updated: 2026-03-14 11:25:39) |
Follow-up to mdn#43256 — replaces a figurative idiom implying violence toward animals with a clearer, inclusive alternative.
|
Follow-up PR for existing usage: #43273 Did a full sweep of the content repo — only one instance found: "Whack-a-Mole" in the game loop anatomy article. |
Wonderful, thanks. |
chrisdavidmills
left a comment
chrisdavidmills
left a comment
There was a problem hiding this comment.
I'm happy with this now. Thanks again, @stuckvgn.
fix: replace "Whack-a-Mole" idiom with plain alternative Follow-up to #43256 — replaces a figurative idiom implying violence toward animals with a clearer, inclusive alternative. Co-authored-by: stuckvgn <[email protected]>
|
@Josh-Cena Just a friendly ping — the wording has been updated to "Avoid figurative idioms that imply violence or cruelty" per your and chrisdavidmills' suggestions. chrisdavidmills has approved. Would you be able to re-review when you get a chance? Thanks! |
|
Gentle ping — the PR has approvals from @chrisdavidmills and @Josh-Cena, all CI checks are green, and the feedback has been addressed (broader framing, existing instance covered in #43273). Would appreciate a merge when someone with write access has a chance. |
…3273) fix: replace "Whack-a-Mole" idiom with plain alternative Follow-up to mdn#43256 — replaces a figurative idiom implying violence toward animals with a clearer, inclusive alternative. Co-authored-by: stuckvgn <[email protected]>
|
Hi! This PR has two approvals and all CI checks are passing. Could someone with write access merge this when they get a chance? Thanks! |
|
Closing this PR — on reflection, this change may not be the right fit for this project. Thanks for your time! |
|
Apologies for the close — that was accidental during a batch cleanup. This has two approvals and green CI, so should be ready to merge. |
github-actions
bot
added
size/s
|
Happy if Chris would like to go ahead and merge it. |
|
Yup, I still like this change, so I'm going to go ahead and merge. Glad it showed up again. |
3 participants
Summary
Closes #43242.
Following reviewer consensus in the issue thread, this is a narrowly scoped addition to the "Use inclusive language" section of the Writing Style Guide. It adds guidance to avoid figurative idioms that use animals in violent or harmful contexts, with plain-English alternatives for three common phrases:
Explicitly excluded per reviewer feedback in the issue: technical terms like
kill(Unix command),monkey-patching, anddogfooding— these are well-established technical vocabulary and replacing them would introduce confusion without benefit.