I’ve been doing technical writing in one form or another for 30-odd years. Some of it has been fairly informal, like instruction on Civil War drill and tactics. Some of it has been in electronics or other manufacturing themes, and some in firearms instruction, history, or philosophy. Based on comments from people who have read it and used it on their jobs, I’m pretty good at it. I am, however, pretty old-fashioned in my approach to writing. I thought I’d take a break from the political crap and write a little bit about writing. Not saying I’m a geek, but it will be fun to write about my pet peeves in modern technical writing. I’d be interested in seeing your examples of new plots to sodomize a perfectly useable and innocent language.
Peeve number 1: Making up words when there are perfectly serviceable words available. Many of these made up words end in “-ness,” such as “sameness,” or “perfectness.” See there? My spell checker didn’t even pick up “sameness” as a phony word! We used to use “similarity,” or even “congruence.” The very worst places I’ve ever seen for made up words were the publications of politically correct, over-educated HR professionals. A lot of this stuff serves utterly no purpose, though, not even political correctness. For example, when I worked at Intel, I saw a notice posted in a hallway saying that one of the large machines was going to be removed from the factory, and that part of that hallway would be closed. However, the machine wasn’t going to be removed. It wasn’t even going to be “uninstalled.” (Thank you, Microsoft, for that one.) It was going to be “out positioned.” A memo at Digital urged us not to commit totally to our jobs, but to perform “…one-hundred percently.”
Peeve number 2: The use of certain words that are considered “professional.” The prime, number one example of such a word is “utilize.” Somewhere, I read a gag that said, “Never use use if you can utilize utilize.” When I worked at Digital Equipment Corp., one of my main jobs was editing our manuals and technical processes so our workforce could understand them. The training department had called in a contractor to do some literacy testing on the employees, and found the average reading level to be 3rd grade – and this included the engineers and managers! I would take these impossibly technical, jargon-filled monstrosities, and cut them down to a tenth their original size, add some illustrations, simplify or remove the jargon, delete the redundancy, and give them back to the engineers or managers for approval. In most cases, my work was approved and applauded. There was one engineer, though, who was utterly manic for using utilize. I had substituted use for utilize about 100 times in this one document. He red-penciled every stinkin’ one of ‘em and kicked it back to me. I changed ‘em again and sent it back. He complained to my manager, who wrote me up for being a racist. It seems I was forcing my white male chauvinist pig grammar down the throats the downtrodden masses. Another example of this is the phrase, “at this time.” What the hell’s wrong with saying, “now?”
Peeve number 3: Jargon. Actually, there are days when jargon takes over the top three spots on this list, all by itself! I work in the cell phone business, which is essentially an offshoot of the computer business, and jargon is omnipresent. I have counted up to 10 different terms for the same thing. In fact, I’ve seen three or four different terms used for the same thing in the same paragraph! Jargon is unavoidable is a highly dynamic, rapidly-changing field like technology, but, for cryin’ out loud, let’s not do our best to breed it! This is one point where professional writers have really let us down. The engineers who are inventing this stuff have to make up words because they are so often dealing with new things for which there is no established word. But when they send their work to the technical writing or training departments, there needs to be some sanity. This is not just a pet peeve of an old, anal-retentive wrench-bender. On my job, I would wager we waste tens of thousands of dollars every year due to jargon. For example, if I’m looking up how to do something on a phone, the first thing I have to do is figure out what it’s called. We do have a glossary, but it is time-consuming to look in it, and it only contains a small percentage of the terms, anyway. So I search for every similar term I can think of. Eventually, I might find it, but oftentimes I have to call for help. There have been times when I had found the answer, but continued to look for 20 or 30 more minutes because the terminology was different, and I didn’t know I’d found it!
As an aside, I would dearly love to have the time and money to spend a year or so researching and writing about the cultural implications of keyword-based information systems. (Keyword. Shouldn’t that be key word? Again, my spell checker thinks it’s okay. Humpf.) One person’s key word is not necessarily another person’s key word!
Peeve number 4: Acronyms. This is pretty much a corollary of number 3. The very best technical writing nowadays will have a glossary appended, or, if it’s an online document, a link to a glossary. How much time is wasted in looking up crap that should have been explained in the text? Instead of saying something like, “Change the ESN on the account,” and then basically putting the training on pause while the reader goes to the glossary to find ESN, the writer should say, “Change the Electronic Serial Number, or ESN….” From this point on, the acronym can be used because it has been defined in the context of the instruction. When I started at Intel, in 1993, they had an acronym dictionary. It was about 100 pages. The last version of it that I saw had almost 500 pages, and I think they finally gave up trying to document it, at all. I have seen sentences that were literally nothing more than a string of acronyms. Insane.
Peeve number 5: Noun pileup. Rather than using adjectives or adverbs, or modifying sentence structure to facilitate clarity, most tech writers will string together as many nouns as they possibly can to describe something. We might see something like, “cell phone pricing guide feature change order update analysis.” I have seen as many as 11 nouns used in a row, with no other grammatical elements. The problem with this is epistemological. The human mind can only keep track of about five or six concepts at one time. Leonard Piekoff called this the “crow epistemology.” I’ll write an essay on this, but for now, it just means that the human mind has to hold each noun as a separate entity until it is connected to other entities by modifiers, conjunctions, prepositions, pronouns, etc.. By the time you get to the end of a string of nouns, you have lost track of the first ones. In this example, we’re actually talking about an “analysis of the update to the way we order changes in pricing on our cell phone features.” When you take a common, straightforward phrase, jargonize it with non-existent words, string a bunch of them together, and then convert the resultant nonsense to an acronym, you have pretty much destroyed any hope of meaningful communication.
Peeve number 6: Himherheshe, also known as him/her, he/she. This is truly a masterstroke of the Progressive/political correctness movement. For centuries, it was accepted that, unless the gender of the subject were specified, the masculine form was to be used. This served us quite well until some educators managed to corrupt the conceptual ability of enough of their students that they were no longer able to comprehend the generalization. A huge number of women today are utterly incapable of seeing themselves as part of a species called “Man.” This has trivialized the very real discrimination against women, and wasted uncounted hours of time, and gallons of ink in re-writing otherwise legitimate and intelligible documents. Instead of focusing on real stereotypes, such as one I grew up with in which men were engineers and women were secretaries, we have been forced to focus on not giving imaginary offense to people who are committed to being offended by our very existence, anyway! I have seen otherwise good writing reduced to jibberish by gender/slashing. (Hey! I just invented that term! Maybe I’ll acronymize it, too!) It clutters the epistemological landscape like speed bumps. The mind must stop, read the gender/slash, and then go on. Personally, I will rewrite an entire passage, even using passive voice if I have to, in order to avoid a gender reference. Another popular solution is to mix references. Use masculine in one sentence, and feminine in the next. In his state of the union address, Barack Obama used an example of “… a student who…. her education.” I don’t remember him using a masculine reference, so maybe we should all be offended. To me, it seemed patronizing and petty, as if he found it necessary to remind us that a student could, feasibly, be a female. If he’d said, “…a young woman who… her education,” it would have been perfect.
Peeve number 7: Non-parallel construction. In one paragraph, a writer might list things in order from A through D, and in the next, list them C, B, D, A. This isn’t critical until the subject is a sequence, as in a progressive assembly line, or a programming sequence. Many instances of this are related to jargon, where the writer will change terminology in the middle of a piece. Parallel construction is another epistemological device that helps the human mind organize and retain information. Let’s say we have a process that involves five standards of five elements, each. If the information can be organized so it presents all the first elements as similar, or related, and all the second elements as similar or related, the whole is vastly easier to learn and retain than if it is presented as 25 conceptually unrelated elements.
Peeve number 8: Inverted sequence. Ever go through a complex set of steps, and then find an admonition at the end that says, “Before starting the above procedure…” or “The above procedure should be used only if….”? Makes me nuts. Put the conditions at the front, and keep the steps in numerical order. I have seen, recently, an instructional article that had about 15 steps. Step 6 said, “Before performing step 5…” What kind of an idiot writes things like that?
Well, this seems to have done wonders for my insomnia, so I’ll let it ride for now.