Don’t Write These Words

by JustinLL on 22 April 2009

In my college-going days, one of my Software Engineering courses had a professor who put a sound deal of emphasis on the documentation side of programming — the written description of the solution to the problem our software was trying to solve. For a wannabe English minor with a focus in grammar like myself, his courses were a nice break from all the number- and theory-oriented course load required of the curriculum. I don’t know if said professor is still teaching, and I’m not that concerned, but he was one of the ones who left me with something worth remembering, and that was his list of words we weren’t to use in our writing, the "bad words list." (Surprisingly or not, it’s one of those handouts I’ve held onto all these years later, and I still make some kind of effort not to include those words in my writing, but then I also chuckle a bit when I notice that I have included one.) Long story short, here’s the list as last updated in November 1997:

Bad Words List

Avoid using these words in documents and on tests. They convey little
information and won’t help the reader understand.

  • and/or, etc., misc.
  • It is always possible to re-write the sentence to remove these vague terms.

  • basically, basic
  • A common speech filler; in a document, it is of the same genre as generally and is basically unclear.

  • compatible
  • These are hundreds of different opinions on this word. Say what you mean.  (e.g. The computer must be able to run Doom.)

  • easy, easier, easiest, easily, simply, hard, harder, hardest
  • These are impossible to test. State some specific number to write a clear sentence.

  • efficient, more efficient, less efficient
  • Unless you are discussing furnaces, this word is vague. Say
    what you mean.

  • flexible, flexibility
  • Unless you are discussing gymnastics, this word is vague. Say
    what you mean.

  • quickly, more quickly, less quickly, fast, faster
  • Same problem as easy.

  • maximize, minimize, optimize
  • These are precise in mathematics; in English they are basically unclear.  State clearly what parameters you are trying to maximize or minimize.

  • module, modular, modularity
  • These terms have a wide variety of definitions, probably more than compatible.

  • user friendly
  • Are you kidding?

  • usually, generally, should, probably
  • These are all of the same, unclear, genre. Write what you mean.   Document readers hate these words.

  • very
  • If emphasis is needed, use a precise word.

###

{ 5 comments… read them below or add one }

Angus Gordon April 22, 2009 at 21:51

Hmmm. Well, I agree with many of these, at least for technical documentation where precision is essential. But some have me scratching my head. “And/or” isn’t the slightest bit vague: it’s actually a precise alternative to “or”, which in natural language *is* vague. You might find it inelegant, but vague is the opposite of what it is.

I’m not a software engineer, but I fail to see how “easier”, “harder” and “faster” are impossible to test. And I always find it amusing when people try to ban bread-and-butter words like “very” – what’s next, “the”?

“Optimize”, though, is one I can get behind!

Reply

JustinLL April 23, 2009 at 21:21

Angus,

You’re right that this list is specific to technical documentation where quantifiability takes precedence over, well, pretty much all else. “and/or” can’t be accurately tested because we don’t know if the coder means the result should be “x and y”, “x or y”, or “x, but not y”. Any of these would be acceptable, even if it were wrong, which is another story.

The same follows for “easier”, “harder”, but not “faster”. (Theta notation.) Easier and Harder are relative terms. “the revised algorithm proved to be easier.” What does that mean, and what am I to test? Was it easier for the programmer to code, or easier for the CPU to compute? Or easier to read because the revised algorithm included descriptive comments?

“very” doesn’t mean anything in technical documentation, and I’m not sure it means a whole lot anywhere else. It can be very difficult to prove.

And, yes, what the heck does it mean to “optimize”?

Thanks for contributing.

Reply

Angus Gordon April 23, 2009 at 21:46

Thanks Justin. I’m sure you’re right that “and/or” is a bad idea in technical documentation. What I was getting at is this: in ordinary speech, “x or y” conjunctions are often ambiguous because they can be interpreted as either including or not including the intersection of x and y. The ambiguity can usually be resolved by context, but not always. If you see “All desserts are served with cream or ice cream” on a menu, you don’t know whether you can have both. “Cream and/or ice cream” makes it clear that you can. (And “either cream or ice cream” makes it clear that you can’t.) So at least in ordinary speech, “and/or”, far from being vague, is more precise than the alternative. (Personally, I’d probably write “cream, ice cream, or both”, but that’s just a stylistic preference.)

Also, the fact that something is difficult to prove doesn’t mean it’s not meaningful! “The meat of this strange animal tastes rather like chicken” is unprovable *and* imprecise, but it’s still a meaningful and useful statement (you know not to eat the stuff if you don’t like chicken). I guess restaurant critics wouldn’t make good software engineers, and vice versa 🙂

(Not sure why all my examples come from food btw…)

Reply

JustinLL April 24, 2009 at 16:12

I think that is the problem, ordinary speech doesn’t have a word for exclusive disjunction the way logic and math have “XOR”. So the use of “OR” in grammar does create an ambiguity, as you pointed out, because, while it’s meant to express inclusive disjunction, in ordinary speech it can take on the role of exclusive disjunction as well. Since most people don’t know about “XOR”, they use the “and/or” notation, which is why I think the professor in question made such a stink about it.

I was only having some fun with “very” when I wrote “It can be very difficult to prove.”

Reply

Angus Gordon April 24, 2009 at 18:10

Oh dear, didn’t even notice that…

Reply

Leave a Comment

Previous post:

Next post: