Make your meaning clear with imperative writing

Write using imperatives so your reader doesn't have to rely on subtlety and implication in your writing. The term imperative is a verb mood that conveys a command or order. In spoken English, imperatives are often considered brusk or even rude, but in written English it's one of the most effective ways to guarantee clarity.

What is an imperative?

An imperative is not a request. It is a command.

Phrases like Press the button or Do not open the panel are imperative. A grammar nerd might notice that the verb is in the present tense (not past, not future). The direct object appears after the object, which makes it easy to differentiate what is doing the action and what is having an action done to it.

These are not imperatives:

• Will you press the button?
• You will press the button.
• When the prompt appears, you will press the button to continue.
• To continue, the button will be pressed once the prompt appears on screen.
• When a prompt is seen, the user will take the action of pressing the indicated button.

As you can tell from these examples, a sentence often becomes longer and harder to parse the more the writer avoids using an imperative. What starts as a simple instruction, like Press the button when you see the prompt becomes almost indecipherable once you rearrange the words to avoid demanding an action of your reader.

Why writers avoid using imperatives

In spoken English or in written opinion pieces, an imperative is sometimes considered overbearing and presumptuous. Instead of demanding that someone takes a specific action, you probably sometimes use phrases like Would you kindly? or I'd like to recommend or What if you tried this and so on. Your specific instruction emerges gently through the course of conversation as you persuade your listener to take whatever action you want them to take.

This works pretty well in most casual and non-urgent settings. In some situations, even in spoken English there's occasion to use imperatives. For example, when something is literally imperative it takes priority over everything else, and so you probably use imperative speech: Don't press that button or you'll lose all your work.

Imperatives are also useful when you're specifically asked for instruction. When someone asks you which port to plug a cable into, and you know that the wrong port would result in a short circuit, it's vital to be clear and direct in your speech. You certainly wouldn't say In my opinion, you could try the blue port because that makes it seem like both options are valid. In this case, it's irresponsible to just insinuate the correct option. Instead, you'd use an imperative: Plug it into the blue port. Do not plug it into the orange port labeled 'High Voltage,' or you'll fry the circuit board.

How to use imperatives

If you write the way you talk or think, you might find yourself avoiding imperatives because you don't default to them when you speak.

To train yourself to use imperative statements in your documentation, create a list of the steps your reader must take to achieve the result you're writing about. Don't write these steps as complete sentences, just write the minimum number of words required for each step to be clear for yourself. Once you've got your list, rewrite each step using these rules:

• Each step must be only a single sentence, and all verbs must be imperative.
• Split any compound sentence into two small sentences.
• Don't use future tense.
• Don't use gerunds (verbs that end in -ing).

Once you've rewritten all the steps in this way, use each step as the thesis statement in a series of paragraphs explaining the context around each step. When you've finished, you've completed at least one section of your documentation.

Imperatives are clear

Success is the reasonable expectation for technical documentation. When a reader commits to reading your documentation, they are accepting an implicit agreement with you. While they are engaged in the activity described in your documentation, as long as they follow your instructions, their end result will match the result described by your documentation. It's a recipe.

There doesn't need to be any illusion of polite conversation or even freedom of choice in technical documentation. Every reader understands that they aren't required by law to follow your written instructions, but by reading your documentation every reader is choosing to follow your instructions. You don't have to convince your reader of an opinion, or cajole your reader into taking orders from you, or dissuade a reader from doing something that could cause problems. Your reader has accepted the social contract of technical documentation. You tell the reader what to do, and the reader follows the steps. Should your reader choose to deviate from your instructions, then it's understood (or at least it's defensible) that this could change the end results of the process described in your document.

In other words, a reader wants imperatives. Your reader wants clear instruction. Your reader doesn't want to interpret hidden meanings and insinuations. If you present options to the reader in such a way that all options are equal, then the reader has no choice but to assume that any option produces the same result. If that's not true, then you must use imperatives to communicate that to your reader.