How Not to do Tech Writing

I dare say this Boomerangs comic speaks for itself…

Do I need to belabor the point? Tech writing should be so plain and clear that you don’t notice the writing! Send for that five critical techniques for good writing document I mention in the column on the right if you don’t believe me, or if you want some good advice.

Someone Gets Enormity Correct

I suppose this is another one of my pet peeves. Enormity means “extremely bad,” not “extremely large.” ‘Nuff said.This is most of one panel from a longish narrative about a visit to a post-apocalyptic—well, here’s the link. Not my kind of adventure, but at least he got “enormity” right.

The Only Time I Recommend Using “It”

That headline is a bit strong, but I want to keep the title to this post short.

To clarify,

  • I generally recommend against pronouns altogether because your reader might not understand what word (called the antecedent, by the way) the pronoun is referring to. Do a search on “pronoun” in the upper right corner of this page to find several more posts on the subject of avoiding pronouns.
  • I also tell you not to use false subjects, one of which is “It is.” See also “There is” and “There are.” Make your sentences name the guilty party!

Here’s a comic that illustrates a point I made in that post about false subjects; the weather can have a false subject:

Mr. Bucket’s hair looks funny drawn from the back.

Lesson in a Pun

English is replete with words that are pronounced the same, but spelled differently, and have different meanings. Peek and peak, for instance. We call these homonyms. Here’s another one, not as common, perhaps, but I still recommend you get these right:

Thank you, Hägar the Horrible.

A Standing Joke

The protagonist in Darren Bell’s strip Candorville is a writer. Hence, like me he’s somewhat of a grammar curmudgeon. Darren must figure that this lesson needs repeating, because I’ve seen this conversation before.

He’s absolutely correct, too.  Myself, I prefer to shop at grocery stores whose express lane says “15 or fewer items.”

Why Pronouns are Dangerous

Remember, folks, this site is not about politics. I ran into a sentence in a political context, though, that is such an excellent example of why I recommend against pronouns, that I have to quote it.

“The president believes in making sure that information is accurate before pushing it out as fact, when it certainly and clearly is not.”

What does that second “it” refer to? I predict that people will choose the antecedent based on their politics. And well they might. The sentence is not a good one, semantically speaking. It is hard to tell what the sentence literally means.

The rule with pronouns is that they should refer to the closest noun. This rule is so easy to break that ambiguity often results, and that’s the case here, and ambiguity is not something you want in a contentious environment.

I think this is what the speaker intended to mean (edited to remove ambiguity):

“The president believes in making sure that information is accurate before pushing [the information] out as fact, [especially] when the [so-called] information certainly and clearly is not accurate [to start with].”

Here’s what the grammar says:

“The president believes in making sure that information is accurate before pushing [the information] out as fact, when the [claimed] fact certainly and clearly is not accurate.”

I think That’s what was meant. Hard to tell. The second version is self-contradictory. Don’t jump all over me if you think I got it wrong, but feel free to put your own translation in the comments.

The rule: avoid pronouns. Say exactly what you mean.

 

Pet Peeve Day Three

My peevishness is aroused when people use transitive verbs as if they were intransitive, particularly “display” and “complete.”

Enough jargon. Here’s a definition by example:

When you display, you display something. When you complete, you complete something.

Back to jargon: That word “something” is called a direct object, and transitive verbs always have one. Intransitive verbs don’t have to have one: you can think, you can suppose, you can walk, you can appear or disappear (in a puff of smoke, perhaps), all without having to put something after them. That’s intransitive.

Here’s an article where they (The National Oceanography Centre in the UK) do it wrong in the headline, then do it right in the article (with a different verb, but you get the point):

The COMICS expedition completes

The COMICS team  The first COMICS expedition reached a conclusion just before Christmas, having collected a great data set on biological carbon in the Ocean’s twilight zone.

I suppose we grammar curmudgeons will have to get used to this solecism, especially the one with “display,” because computer instructions are so common. But when you press Enter, the window doesn’t display, it appears!

Harrumpf.

 

Pet Peeve of the Day: Prior

Priority is when something has to come first because of importance or its place in a series of steps. For example, “my wife has a prior claim on my affections.”

If all you mean is earlier of before, say that. Here’s an example of this misuse of prior. Two, actually:

Using our system, we detect anti-adblockers on 30.5% of the Alexa top-10K websites which is 5-52 times more than reported in prior literature. Unlike prior work which is limited to detecting visible reactions (e.g., warning messages) by anti-adblockers, our system can discover attempts to detect adblockers even when there is no visible reaction.

All they mean is earlier. I’m pretty sure these folks aren’t suggesting that the earlier literature and work are more important or ought to be read first.

Should I also mention their misuse of “which” when they should use “that”?  Nah, I already covered that.

Academics can be so pretentious. Harrumph.

Pet Peeves Make for Easy Posts

My pet peeve for today, class, it the phrase “glossary of terms.”

A glossary is always of terms, so adding “of terms” is unnecessary (read “redundant”). You may, however, use “terms” if you include a limiting adjective. You might say “glossary of unnecessary terms,” for instance.

I like the strip Pajama Diaries. Once a month, though, Terri Libenson makes me cringe with her once-a-month series of that title. Here’s the latest:

If you care to see the whole series, here’s a link to them all. I think.

And “glossary” all by itself is just fine. Harrumpf.

PS: Did you notice that I repeated myself in that sentence just ahead of the comic? I don’t normally do that (it’s redundant), but it was a good chance to use the phrase “once a month” both as a compound adjective, and not.