Toward More Accurate Technical Writing

J. Touch
July 26, 2020

The following list of terms have unfortunate connotations that
complicate their meaning in technical documents. As such, they should
be replaced with suggested text as indicated where possible.

NOTE: references to legacy and external document uses should not be
replaced but can be clarified by also including the preferred terms below.

Please contact the author with suggestions or comments.

phrase
“REGEXP pattern”
meaning
alternates


Terms appearing in RFCs, as well as possibly other technical documentation:

master – slave
“\W(master|slave)”
dominant/subordinate parties (note that “master” alone still carries this implication)
primary/original/main/source – secondary/alternate/replica/copy (e.g., for databases)
parent – child
speaker/talker – listener
leader – follower/minon
dominant – subordinate
actor – reactor (e.g., for flip-flops)
bootable – non-bootable (e.g., for disk drives, which don’t actually link to each other anyway)

grandfather(ed)
“\Wgrandfather”
exceptions granted by nature of being preexisting
legacy, legacied

whitewash
“\Wwhitewash”
mask flaws using a coat of thinnned white paint
cover-up

blackhat or whitehat
“\W(black|white)(\W|-)?hat”
bad/evil actor, good actor
ally, adversary

black and/or white
“\Wblack\W(and|or|and\/or)\Wwhite”
binary decision with preferred (white) outcome
binary, all-or-nothing, clear choice

greylist
“\Wgreylist”
intermediate between list of accepted and denied entities
partial accept or admit

dummy
“\Wdummy”
person of low intelligence, often used to represent something useless or meaningless
placeholder

sanity check, reality check
“\W(sanity|reality)\Wcheck”
simple or rapid check, often cursory
validity check / correctness check / confidence check / quick check

bitch
“\Wbitch”
euphemism for complaining (or complainer)
complain(er)

hobble(d)
“\Whobble”
to render handicapped by breaking one’s legs
undermined, made less effective by

he, she, his, her(s)
“\W(he|she|his|her(s?)\W”
gendered pronouns referring to people
they (even as singular)

dude, guy
“\W(dude|guy)”
casual reference to a person (typ. male)
(replace with a different phrase)

first, second, third world
“\W(first|second|third)\Wworld”
groups of countries ordered during the Cold War
tech-rich, tech-poor, tech-evolving
resource-rich, resource-challenged

developed, developling, underdeveloped countries
“\W(under)?develop\w+\Wcountr”
groups of countries ordered by implied maturity compared (typically) to the state of wealthy countries
tech-rich, tech-poor, tech-evolving

mafia, mafioso
“\Wmafi(a|oso)”
organized crime, often implying a closed group that circumvents laws or policies
outlaw(s)


Terms not yet appearing in RFCs that should also be considered:

greybeard
“\Wgreybeard”
male elder/senior member of a community
senior member

gyp
“\Wgyp(ped|s|ping)\W”
swindle, cheat
swindle, cheat


The following terms are NOT currently believed to be problematic:

black, red
network security levels

black and white
when referring to images created from those two colors

dark web, dark net
dark here refers to “unlit”

grey web, grey net
grey here refers to partially dark
dim web, dim net may be more accurate

white pages, yellow pages
refers to historical use of paper of those colors to publish phone directories

white paper
a brief though-piece

black hole
an area with the absence of light, notably the astronomical object from which nothing gravitationally escapes

black box
a container whose interior remains unknown (unlit)

red, green; red, yellow, green
implications for permit, caution, deny based on traffic lights

red
impication of warning based on use in lighting