Add speciesist language to inclusive writing guidelines

[stuckvgn]

Proposal

Add guidance on avoiding speciesist language to Docusaurus's documentation, both for the project's own docs and as a recommendation for users building documentation sites.

Docusaurus is uniquely positioned: it's not just a project with docs — it's a documentation framework used by thousands of projects. Writing guidance from Docusaurus carries outsized influence on technical documentation across the ecosystem.

Examples and alternatives

Speciesist term	More precise alternative	Why
Canary deployment/release	Progressive rollout	Describes the actual process, not a reference to sending canaries into mines to die
Dogfooding	Self-hosting, internal testing	Immediately understood by any reader, including non-native speakers
Cattle vs. pets	Ephemeral vs. persistent	More technically precise
Kill (a process)	Terminate, stop	Already widely adopted

Note: Docusaurus uses "canary" for its pre-release channel and has a _dogfooding directory. This isn't a call to rename everything overnight — it's proposing to document preferred direction and adopt alternatives in new writing.

Why this matters

1. Precision: Animal-derived idioms require cultural knowledge to decode. "Progressive rollout" is clearer than "canary deployment."
2. Internationalization: Docusaurus has strong i18n support. "Dogfooding" has no intuitive meaning in any language. Precise terms translate and localize better.
3. Inclusivity: These phrases normalize violence toward animals, just as master/slave normalized other hierarchies.

Precedent

• master → main (GitHub, GitLab, Bitbucket)
• master/slave → primary/replica (MySQL, PostgreSQL, Redis)
• whitelist/blacklist → allowlist/blocklist
• Inclusive Naming Initiative
• Google developer documentation inclusive language guide

What this could look like

1. A section in CONTRIBUTING.md recommending precise technical terms over animal-derived idioms
2. A documentation writing guide with inclusive language recommendations
3. Gradual adoption in new writing going forward

Reference: Open-Paws/speciesist-language-scanner provides automated detection tooling.

[slorber]

Hey, as a foreign English speaker, I have never thought about these terms being problematic. For "master/blacklist", I can see the problem, but canary/dogfooding are widely used terms in the IT industry, and it's not like animals are going to be offended by this usage.

I don't have strong opinions, but would prefer to keep things as they are today. If the industry moves toward different terms, like it has been the case with the GitHub master/main transition, I'm going to follow.

TLDR: If you can convince the React team not to use the term "canary" anymore, I can consider adopting the new term. Otherwise, I prefer to align with terms used by our upstream frameworks and other popular projects at Meta.
https://react.dev/blog/2023/05/03/react-canaries

[stuckvgn]

Fair pushback on canary — React owns that term in this part of the ecosystem and I'm not asking Docusaurus to diverge from its upstream. That one I'll drop.

The part of your response I'd push back on a bit: "it's not like animals are going to be offended." The parallel argument against dropping master/slave was that enslaved people weren't consulted about database terminology, so why change it. The question isn't whether anyone is offended — it's what we're casually embedding in our shared technical vocabulary.

The phrases that actually concern me aren't the clean tech terms like canary. They're the idioms that reference killing and harm as metaphors — "kill two birds with one stone," "beat a dead horse," "more than one way to skin a cat." Those phrases turn acts of violence against animals into throwaway expressions. Webpack just merged rules flagging exactly these — warning level, not blocking, just a nudge toward "accomplish two things at once" or "belabor the point." Same approach that now flags master/slave in most projects.

Dogfooding is a separate case and honestly your own i18n argument applies there — you mentioned being a non-native English speaker, and that's the point exactly. "Self-hosting" or "internal testing" means the same thing to every reader on earth. "Dogfooding" means something only if you absorbed it from a specific cultural context.

I'm not proposing renaming the _dogfooding directory or the canary channel. Just CONTRIBUTING.md guidance for new prose writing, and Vale warning rules for the violence-referencing idioms. Would a PR scoped to that be worth looking at?

[slorber]

As a non-native English speaker, I understand better "dogfooding" than "self-hosting" or "internal testing". Those are not the same at all to me.

Self-hosting is widely used as a way to deploy software on your own infra. I also use the term dogfooding for things that are not "internal tests" (for example, we may dogfood Docusaurus features on our own documentation, internal testing is only interesting with dogfooding but is not the same thing, not even a subset nor a superset).

For these reasons, I prefer to keep canary/dogfooding for now.

If you notice other problematic sentences, feel free to open a PR with better alternatives. For now, I'd rather not introduce new CI/linting tooling. I'm the main writer of these docs and usually review all docs PR carefully, and I'm not seeing this as a recurring problem.

[Josh-Cena]

Hello @slorber and @stuckvgn, I've given my opinion in mdn/content#43242 which has got support: I strongly disagree that "dogfood" is bad in any way. It has no negative connotations. As for "canary", I'm indifferent on a rename, now that we are out of alpha and we can repurpose alpha/beta for other purposes. In general, I can't care less about these words that have drifted from their original meanings; I doubt an unprimed human would feel harmed by them, unlike other words targeting at humans. Our editorial choices protect humans, not things that can't read.

[stuckvgn]

Fair point on dogfooding — you're right that it carries semantic weight that "internal testing" doesn't fully capture, and I take your point on "self-hosting" already being an overloaded term. I'll drop that one.

I'll put together a PR scoped to prose idioms — the violence-referencing phrases like "kill two birds" etc. No new tooling, just direct text alternatives where they appear. Appreciate the openness to that.

[stuckvgn]

"Our editorial choices protect humans, not things that can't read" — that's the same framework people used to justify excluding any group from moral consideration. The inability to read English isn't a meaningful threshold for whether we should avoid casually referencing violence against someone.

But this doesn't need to be a philosophical debate. The practical argument is simpler: precise technical language is better than idioms that require cultural context to decode. That's a writing quality argument regardless of where you land on the ethics.

[Josh-Cena]

We don't have inclusive language guidelines; writers (which are 99% the maintainers) just exercise their discretion. I don't think it needs to be added because we don't even have normative guidelines in general. If you find any specific instances of dubious language, we can discuss; right now I have expressed my -1 for "dogfooding" and +0.5 for "canary".