←back to thread

Red Hat Technical Writing Style Guide

(stylepedia.net)
186 points jumpocelot | 4 comments | 10 Jul 25 15:01 UTC | HN request time: 0.864s | source
Show context
GLdRH ◴[10 Jul 25 19:09 UTC] No.44524415[source]▶
Section 4.6 is certainly ridiculous, but I suppose you can just ignore it.
replies(2): >>44524795 #>>44524819 #
jacobgkau ◴[10 Jul 25 19:53 UTC] No.44524795[source]▶
> Avoid neurodiversity bias. For example, avoid the terms "sanity check" and "sanity test",

This one seems a little much. I've used this term in work writing within the past week (not in official documentation, but I do also write official documentation). I tried to look up what the acceptable alternatives are (since Section 4.6 doesn't specify one for that rule), but it seems most possible alternatives already have other, distinct meanings: https://english.stackexchange.com/questions/282282/near-univ...

replies(2): >>44525093 #>>44526245 #
1. duskwuff ◴[10 Jul 25 22:11 UTC] No.44526245[source]▶
It's not a hypothetical situation; I know people with chronic mental health conditions who find this usage of the word "sane" specifically hurtful. It's avoidable; use "reasonable" as an adjective and a phrase like "consistency check" as a verb, or a more specific term like "bounds check" if applicable.
replies(1): >>44526950 #
2. bigstrat2003 ◴[10 Jul 25 23:46 UTC] No.44526950[source]▶
Then those people are unreasonable, and need to adjust their outlook. It is neither healthy for them, nor fair to others, to take such great offense at harmless words.
replies(1): >>44527631 #
3. const_cast ◴[11 Jul 25 01:40 UTC] No.44527631[source]▶
But words evolve, and we do actually change which words we use. We've been doing it since... forever. And, somehow, people still manage to act surprised when it happens. As if it's their first day on Earth.

There's a lot of terminology around just mental illness that we have decided to leave in the past. And, a lot of it is for good.

One benefit of changing our language is we get a second chance. We can be more specific, more fine-grained, or more accurate. For example, sanity check is vague. If it's a bound check, we might say bounds check. That's more accurate. If it's a consistency check, we might say consistency check.

We want our language, particularly in technical pieces, to be both inclusive and precise. What I mean is, we want it to include every thing it should, and nothing it shouldn't.

For example, in Medical literature you'll often see the term "pregnant person" or "pregnant people", or even "people who may be pregnant". At first glance, it seems stupid. Why not just say "women"? Women is imprecise. There's a variety of people who would not identify as a woman who may be pregnant. If they get, say, a form with that verbiage they might mark "no, I'm not a woman". But they SHOULD mark "yes, I am a pregnant person" or "yes, I am a person who may be pregnant". It doesn't even just include transgender individuals - it also includes people born intersex, or people born without a uterus who do identify as a woman. There's women who may be pregnant and women who may never be pregnant, just as there are people who do not identify as women who may be pregnant. The word "woman" is then imprecise, confusing, and includes people it shouldn't, as well as excluding people it should.

replies(1): >>44527834 #
4. chris_wot ◴[11 Jul 25 02:17 UTC] No.44527834{3}[source]▶
Yes, they evolve but only if wider society accepts it. And in this case, most people don't consider that it's reasonable to change the phrasing.

This way leads to people writing blog posts about firing workers they don't employ because they used gender non-neutral language in technical posts.