Skip to content

docs: add Vale rules suggesting alternatives to animal-derived idioms#21374

Open
stuckvgn wants to merge 1 commit intogithub:mainfrom
stuckvgn:add-speciesism-vale-style
Open

docs: add Vale rules suggesting alternatives to animal-derived idioms#21374
stuckvgn wants to merge 1 commit intogithub:mainfrom
stuckvgn:add-speciesism-vale-style

Conversation

@stuckvgn
Copy link

Summary

Adds a small set of Vale substitution rules that suggest more precise alternatives to common animal-derived idioms in documentation.

For example:

  • "kill two birds with one stone" → "accomplish two things at once"
  • "guinea pig" → "test subject"
  • "wild goose chase" → "pointless pursuit"
  • "red herring" → "false lead"

The suggested alternatives are often more descriptive and clearer for non-native English speakers, while also avoiding phrases that casually reference animal harm.

Details

Two rule files added under docs/codeql/vale-styles/Speciesism/:

  • AnimalIdioms.yml — 26 substitution patterns for common violent idioms
  • AnimalMetaphors.yml — 8 substitution patterns for objectifying metaphors

All rules are set to suggestion level — they only surface alternatives during writing and won't affect CI or block any workflows.

Context

A growing number of documentation projects are adding speciesism-aware language rules to their Vale configurations (webpack.js.org, Elastic, Datadog, and others), following the same trajectory as the shift from master/slave → primary/replica and whitelist/blacklist → allowlist/blocklist.

The CodeQL docs already enable Microsoft.Gender — this extends that same attention to inclusive language.

References: Peer-reviewed paper on speciesist language

Changes

  • Added docs/codeql/vale-styles/Speciesism/AnimalIdioms.yml
  • Added docs/codeql/vale-styles/Speciesism/AnimalMetaphors.yml
  • Updated docs/codeql/.vale.ini to include Speciesism in BasedOnStyles

Introduce suggestion-level substitution rules that flag common
animal-derived phrases and offer clearer alternatives.
@stuckvgn stuckvgn requested a review from a team as a code owner February 25, 2026 18:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant