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.
- basically, basic
- compatible
- easy, easier, easiest, easily, simply, hard, harder, hardest
- efficient, more efficient, less efficient
- flexible, flexibility
- quickly, more quickly, less quickly, fast, faster
- maximize, minimize, optimize
- module, modular, modularity
- user friendly
- usually, generally, should, probably
- very
It is always possible to re-write the sentence to remove these vague terms.
A common speech filler; in a document, it is of the same genre as generally and is basically unclear.
These are hundreds of different opinions on this word. Say what you mean. (e.g. The computer must be able to run Doom.)
These are impossible to test. State some specific number to write a clear sentence.
Unless you are discussing furnaces, this word is vague. Say
what you mean.
Unless you are discussing gymnastics, this word is vague. Say
what you mean.
Same problem as easy.
These are precise in mathematics; in English they are basically unclear. State clearly what parameters you are trying to maximize or minimize.
These terms have a wide variety of definitions, probably more than compatible.
Are you kidding?
These are all of the same, unclear, genre. Write what you mean. Document readers hate these words.
If emphasis is needed, use a precise word.
###
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!
Comment by Angus Gordon — April 22, 2009 @ 9:51 pm
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.
Comment by JustinLL — April 23, 2009 @ 9:21 pm
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…)
Comment by Angus Gordon — April 23, 2009 @ 9:46 pm
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.”
Comment by JustinLL — April 24, 2009 @ 4:12 pm
Oh dear, didn’t even notice that…
Comment by Angus Gordon — April 24, 2009 @ 6:10 pm