03.01 Common English errors

In English, you can’t say that something allows to do something or forbids to do something without mentioning who is allowed or forbidden. There are a number of permission/prohibition words that act like this:

You could tell the reader who is allowed or forbidden. But if you want to focus on what is allowed or forbidden, such details may distract your reader.

It’s easier to change the way you express what’s allowed or forbidden. Instead of using a to- form (to plant, to juggle), use an -ing form (planting, juggling).

English doesn’t actually use in case or in case of very often. They mostly appear in set expressions, usually for bad circumstances (in case of fire, break glass). There are better choices:

Tone is hard in writing. How direct can you be when you’re telling someone to do something?

In email, it’s often politer to name a need and let the addressee decide to do something about it. You’re telling your reader that you trust them to do what they feel is necessary.

Technical writing is different. You’re assuming that your reader doesn’t know what to do, or they’d be off doing it instead of reading the documentation. They want to be told, clearly and directly, what to do next. Direct commands reduce cognitive load.

English has different ways for talking about uncertain things. Which form you use depends on how likely the uncrtain thing is. You can think of them in ascending order of probability:

As you can guess from what’s crossed out, technical writing doesn’t use all of these forms.

Documentation doesn’t usually cover unlikely things. Otherwise, it ends up full of edge-case scenarios that are relevant to very few readers. Then most of the audience can’t find the more directly relelvant content.

Stick to content that you expect to happen (will or present tense) and that which you wouldn’t be surprised to encounter (may).

Could/can/will has the same pattern. And like might/may/will, you should only use the likeliest two in technical writing:

In technical writing, things are often named for their relationship to other things. So an API key is a key that allows you to use an API.

When the relationship between the things is many to one, how do you create the name? If there’s a set of names of categories in your code, are they category names or categories names? If a planet killer kills more than one planet, shouldn’t it be a planets killer?

Logic would dictate that the name would reflect the proportions of the relationship.

Unfortunately, English isn’t always logical. No matter how many planets the thing kills, you still have to use the singular.

A good way to remember it is that many apples go into a single apple pie. But it’s still an apple pie, not an apples pie.

English has too many kinds of present tense. Some of them are fancier than others.

The present progressive (is --ing) is pretty fancy. It tells the reader that something is going on, and probably will keep going on.

This fancy present is not usually used in technical documentation. Any time you see it, you can improve the sentence by changing it to the simple present (--s):

WHEN TO BREAK THIS RULE GUIDELINE

There is one case when the present progressive is necessary: after while, used to describe a period of time.

Every language has its own quirks around capitalization. Some things, like names of people and places, are capitalized pretty much everywhere. Other things vary from language to language.

Too much capitalization can be a problem: