Unexpected Grammar Curmudgeon

Well, punctuation curmudgeon. It’s Linus Torvalds, the writer (inventor? developer? founder?) of the computer language Linux. I didn’t expect this from him. In fact, I tend to feel that computer languages manage their own grammar and punctuation by not working if you do it wrong.  He recently expressed an opinion about commenting. Comments in computer code are passages for humans to read, that presumably explain what’s going on, but the code itself doesn’t need them. You tell the computer that a passage is a comment with punctuation (that varies from language to language) at the beginning and end of the comment. Here’s a summary of what he said:

He likes this:

/* This is a comment */

He also approves of this:

/*
* This is also a comment, but it can now be cleanly
* split over multiple lines
*/

But he disapproves of this:

(no)
/* This is disgusting drug-induced
* crap, and should die
*/

(no-no-no)
/* This is also very nasty
* and visually unbalanced */

“I’m not even going to start talking about the people who prefer to ‘box in’ their comments, and line up both ends and have fancy boxes of stars around the whole thing,” he adds. “I’m sure that looks really nice if you are out of your mind on LSD, and have nothing better to do than to worry about the right alignment of the asterisks.”

You get the idea. His original essay was quite a bit spicier, and not suitable for a family blog such as this one. If you follow the link, you can start right below the horizontal line.

Subscribe to this blog's RSS feed

Sometimes a prefix or suffix becomes popular, and people start adding it to lots of words where it never used to occur. When this happens, we say the word part has become productive. A couple decades back, when skirts began to shorten, the prefix “mini-” became productive. I remember a quip from Readers Digest or someplace mentioning how disconcerting it was to see a mini-skirt on a maxi-mum. Mini was so productive it even promoted its antonym! Things have settled down by now, and we see mini and maxi attached to words without being considered remarkable.

Here’s a suffix that’s apparently become productive that I didn’t happen to know about.  I saw it in a recent Blondie. As usual with a newly productive linguistic item, people make fun of it.

This blog is about expository writing—explaining things—but a headhunter technical recruiter recently asked me what a technical writer does, and my answer was the germ for this post. Technical writing is a subset of expository writing, but it’s a pretty large field. Here are my thoughts on the subject.

Technical writing consists of four main writing-related activities; two main ones, and two more generic activities.

Writing instructions. This, I think, is what most people think of when they think of tech writing. The readership is people who don’t know how to do something, want to be able to do it. I tell people it’s “Put tab A into slot B.” It typically looks like a paragraph telling what’s to be accomplished, then a set of steps, numbered, with an illustration for each step. Repeat as necessary. You generally see a cover page of some kind, maybe a table of contents, and sometimes some sort of reference (appendix) in the back. When you write instructions, get someone to follow them! Watch them make mistakes. The mistakes show what’s wrong with the instructions. Fix the instructions.

Describing progress. The main readership of this material is colleagues and people who are checking up on what’s going on; managers, auditors, regulators. I suspect more tech writing is this activity than any other. Projects, especially large ones, especially software development, especially when someone is checking up on things, are the arena for this part of tech writing. Even a project as small as building a deck on the back of the house uses this kind of documentation. You need a description of the deck, a bid from the contractor, plans, a bill of materials, and the invoice. Those are all technical documents. Build a bridge, rocket, or office building, and you have those documents in spades. The description becomes specifications or requirements, for example. In the financial industry, banks have to create descriptions of several stages of their software development projects, partly to convince auditors and regulators that the bank is being responsible in the handling of customers’ money. Even the regulations are technical documents. These descriptive documents have to describe everything. Think detailed lists of requirements, records of meetings where people decided what to do,  detailed lists of tests, reports of the test results, reports of reviews of the computer code to demonstrate there’s nothing malicious in there, the list goes on and on.  Most of these documents aren’t very glamorous, but they can be important. What if the tech writer had been careless describing the contents of the Apollo 13 space capsule? They used that information to figure out a way to scrub carbon dioxide out of the air, saving the lives of the entire crew!

Helping marketers. I think I’ve said before that tech writers regard all marketing people as insane. But technical things need to be sold, too, and described both convincingly and accurately. White papers, proposals, grant applications are all documents whose purpose is to sell something, and they need to be accurate. Tech writing is the part that makes sure that brochure is telling the truth.

Editing and proofreading. Over the years I’ve checked restaurant menus, résumés, newsletters, ads, brochures, even kids’ reports for school. Many people are careless or unskilled about the mechanics of the language, and the wise get someone to look over their work. Tech writing is helping people not look dumb.

Maybe you’re a tech writer reading this. Did I leave anything out?

Sometimes I think we could use a punctuation mark between the comma and the semicolon. Something for when you’re using commas to separate items in a list, but you need something a little stronger to separate the whole list from other parts of the sentence. Here’s an example from Gizmag:

In the mysterious microscopic realm where the electromagnetic fields of light and matter intimately intermingle as they exchange energy, plasmons, excitons, and other particles with unexpected and usual properties abound.

You have to read that sentence twice to understand it once! The sentence is perfectly correct grammatically (if you excuse saying “microscopic” when you mean “submicroscopic”), but you can’t tell that “energy” isn’t part of the list that starts with “plasmons” until you get clear to the last word in the sentence! The sentence is correct, but it’s bad writing because it’s not clear.

Well, I’m not going to get anywhere lobbying for new punctuation. What’s the best way to fix this? Recast the sentence. Something like this:

In the mysterious microscopic realm where the electromagnetic fields of light and matter intimately intermingle as they exchange energy, particles with unexpected and unusual properties, such as plasmons, excitons, and others, abound.

We separated the list from the prepositional phrase that begins the sentence. Confusion gone.

The sentence is still rather long. How about this?

In the mysterious microscopic realm where the electromagnetic fields of light and matter intimately intermingle as they exchange energy, particles with unexpected and unusual properties abound. These include plasmons, excitons, and others.

Better.

Do you know why that comma is after the word “energy? The rule is that if a sentence starts with a prepositional phrase that has more than five words, separate the phrase from the rest of the sentence with a comma. This one has twenty words. Quite a mouthful.

Usually unnecessary, anyway. Not counting “please,” see a recent post. My term for unnecessary words is fluff. Don’t write fluff.

Successfully. If you did something successfully, you did it. No need to add “successfully.” Here’s a recent headline I saw in Inside Climate News:

Iceland Experiment Successfully Turns CO2 Emissions into Rock

Some might argue that the word implies that the success was a surprise, but face it—the headline works just fine without “successfully,” and turning a gas into rock would be surprising in any case.

I see a lot of pages on which a person applies for a job. They usually end with something like

Congratulations. You have successfully submitted your application for the position of whatchamacallit with our company.

Why not say something like “We got your application and we’ll take a look at it.”? (see an earlier post about using the future tense to be vague.)

Different. When you mention two (or more) things, you often don’t gain anything by saying they’re different, unless the difference is the point. Usually, if they’re different enough to enumerate, you have already made them enough different that you don’t need to say so.

The farm has two different bulls.
The farm has two bulls.

His wife has twenty-four different chickens.
His wife has twenty-four chickens.

There are two ways to hold a trombone.
There are two different ways to hold a trombone.

Conciseness is a virtue. (Technically it’s “concision,” but it’s also a virtue to be clear.)

Totally. I was talking with my daughter (not the one who wrote the guest post) about unnecessary words, and she suggested “totally.” If something is so, it’s totally so unless you say otherwise. Since a lot of things can be incompletely so, be sure to say so.

The poor creature was dead
The poor creature was totally dead.
The poor creature was half dead.

Unless you’re  Valley Girl, totally.