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.

“REGEXP pattern”

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

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)

exceptions granted by nature of being preexisting
legacy, legacied

mask flaws using a coat of thinnned white paint

blackhat or whitehat
bad/evil actor, good actor
ally, adversary

black and/or white
binary decision with preferred (white) outcome
binary, all-or-nothing, clear choice

intermediate between list of accepted and denied entities
partial accept or admit

person of low intelligence, often used to represent something useless or meaningless

sanity check, reality check
simple or rapid check, often cursory
validity check / correctness check / confidence check / quick check

euphemism for complaining (or complainer)

to render handicapped by breaking one’s legs
undermined, made less effective by

he, she, his, her(s)
gendered pronouns referring to people
they (even as singular)

dude, guy
casual reference to a person (typ. male)
(replace with a different phrase)

first, second, third world
groups of countries ordered during the Cold War
tech-rich, tech-poor, tech-evolving
resource-rich, resource-challenged

developed, developling, underdeveloped countries
groups of countries ordered by implied maturity compared (typically) to the state of wealthy countries
tech-rich, tech-poor, tech-evolving

mafia, mafioso
organized crime, often implying a closed group that circumvents laws or policies

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

male elder/senior member of a community
senior member

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

impication of warning based on use in lighting