The Present Tense in Technical Writing

rogersgeorge on October 14th, 2017

Here’s the rule:

Use the present tense to indicate customary behavior, no matter when it happens.

That’s right, when you do something, something happens. Doesn’t matter whether you’ve actually done it yet. Here are a few examples:

When true, the boolean indicates acceptance; when false, it indicates rejection.
When you press Enter, the window appears.
When I get hungry, I eat!
Tomorrow I go to the dentist.
Every day I get up before 6:00.

Maybe you’re writing instructions for operating a machine that hasn’t even been built yet. Use the present: When you turn the key, the engine starts.

When may you use the future? I can think of four times:

  • When you want to be vague:  Someday we will get married.
  • When the time is important:  Tomorrow I will go to the dentist, but the next day I won’t
  • For a command:  You will clean your room! (In military tech writing they use “shall.”)
  • When something isn’t customary: We will go on the trip if we can ever get the car started.

By the way, this is a good rule even if your writing isn’t strictly technical.

Subscribe to this blog's RSS feed

You have a choice: If or Whether

rogersgeorge on October 10th, 2017

If you’re a programmer, you know about “if.” We even call then “If statements.”

If some sort of code thing,
then some sort of code thing
else some other code thing.

We also have conditional sentences in English that have an analogous structure.

If you have short hair, it’s pretty hard to tie a ribbon in it.

But there’s another construction where the “if” is more or less in the middle of the sentence, and here it can get tricky, because you can put “whether” in the same spot where the “if” goes, but the meaning is significantly different. In this case, the “if” refers to what came before in the sentence, and “whether” refers to what follows.

The light tells you if the door is open. (Otherwise it doesn’t shine.)
The light tells you whether the door is open. (Maybe different colors of light for open and closed)

The message tells you if the car is ready. (Otherwise, it doesn’t tell you.)
The message tells you whether the car is ready. (The message says “car is ready,” or “car is not ready.”)

In other words, the “if” applies to what comes before, and it tells of the existence of what comes after.
But “whether” applies to what follows, and shows an alternative.  I should add that “Whether” always implies or says “or not.” If you can fit “or not” into the sentence, you should use “whether.”

Using “if” when you should use “whether” is easy, but don’t do it. Your meaning will be crisper, and nobody will get a mental hiccup from getting your meaning wrong at first.

Watch your Place!

rogersgeorge on October 8th, 2017

This kind of mistake is mainly a result of carelessness, I think. Some words refer to points in space, not general areas. These include “center,” and “base.” Here are two examples of doing it wrong. They both treat these points as vague areas that you hang around the edges of.

Usenet’s creation was based around the idea that computers were becoming sophisticated enough that they could be used to hold conversations, and there was plenty of conversation going on.

Beverly Hills, 90210 originally centered around Brenda (Shannen Dougherty) and Brandon Walsh (Priestley), middle-class high-school-age twins from Minnesota who relocate to ritzy Beverly Hills with their parents.

Your base is a single place—you’re based on something. (Don’t say “based out of,” either.) Same for “center.” You should be centered on something.

These examples of muddy thinking are not a good thing when you explain something. You need to be precise. Maybe you can get away with it when you do a grocery list. That food is around here somewhere…

PS—After I finished this post, I ran into a good example of “based out of,” which I repeat, you shouldn’t write. Use
based in” or “based at.”

The Metric Geometry and Gerrymandering Group, based out of Tufts University is leading the charge to build a consensus on how math can make better districtings.

It’s a graphic article, but it’s worthwhile. Find the article here.

Compound Objects

rogersgeorge on October 6th, 2017

I suppose this Beetle Bailey comic is a repeat of the second-oldest joke in the book, descending as it does from sixth grade English (Hi, Mrs. Clemens!). Lots of folks get confused when they have two objects of a single preposition, and the mistake is so common that I decided to repeat the joke as a reminder. The trick, by the way, is to think the phrase without mentioning the other guy; then it’s easy to get the correct word.

The other second-oldest joke, I suppose, is the one about the restaurant manager who goes someplace else to eat.

What??? You want to know the world’s oldest joke? Well, just between you and (ahem) me, it’s somewhat scatological, so I won’t repeat it here, but they found it on a cuneiform tablet that dates to about 4000 years ago. Google “oldest joke.” Reuters has a short article about it.

Fluff!

rogersgeorge on October 4th, 2017

The time has come to write about fluff again—I ran into a comic on the subject. We curmudgeons also call fluff redundancy, wordiness, and unnecessary verbiage. Probably some saltier terms, too. Fluff is the antithesis of conciseness, one of my gold rules for good writing.

I’ve featured this gal in Jump Start before. Several times, actually; that one was just a sample.

So when you write, look over what you wrote. (You always proofread, don’t you?) Do you see any words that you could delete without changing the meaning? Delete ’em! Your readers will thank you.