"Allows You To" considered harmful

Most of the time, it just obscures meaning. Even when necessary, it has a shorter alternative.

The Forward feature allows you to forward messages…

This is one of the most common constructions in technical documents—and one of the least useful. In fact, you can always avoid the phrase “feature allows you to verb” and your docs will be better off:

• The phrase often incorrectly implies an intermediary between a behavior and its result.
• Even when an intermediary is necessary, the semantic meaning of allows is ambiguous.
• Even when the phrase is appropriate, it has a shorter alternative, lets you.

That’s the gist. The following sections elaborate with examples, citations, and proposed alternatives.

Reasons to avoid “allows you to”

In short, the phrase always creates inaccuracy, imprecision, or unnecessary text.

It’s often inaccurate

Along with similar constructions like lets you or enables you to, allows you to can create an unnecessary grammatical layer between a feature and its behavior. In linguistic terms, such verbs are examples of catenative verbs, meaning they subordinate other verbs in a chain. More specifically, they are examples of causatives, verbs that “cause” some other action. ¹

But these constructions often describe behavior that has no secondary effect. Let’s return to this text, lifted from an old version of the WhatsApp documentation (now fixed): ²

The Forward feature allows you to forward messages from a group or individual chat to another group or individual chat.

Is this true? Does the forward feature allow me to forward messages, or does it forward messages? Why not describe behavior directly?

The Forward feature forwards messages…

Maybe that example sounds awkwardly redundant, but unnecessary catenative verbs commonly intrude in all sorts of technical description. For example, this is from the MDN JavaScript reference.

Window.cancelIdleCallback()

Enables you to cancel a callback previously scheduled with Window.requestIdleCallback.

What does the method do: cancel callbacks or enable cancelling a callback elsewhere? Though this example uses enables instead of allows, the effect is the same: unnecessary words and increased ambiguity.

Its meaning is often ambiguous

Sometimes a writer really does want to describe a feature as a means to some end. In this case, a catenative verb might be appropriate. For example, these are from the MDN docs:

Making a copy like this allows you to effectively use the request/response again while varying the init options

The Twitter API allows you to do things like displaying your latest tweets on your website.

Both of these sentences describe one action (making a copy, calling the Twitter API) that can help users accomplish some later action (reusing, displaying). So causatives seem appropriate. But even in these cases, are phrases like allows you to or lets you really the best constructions?

If you look up allow or let in any dictionary, you’ll find the first definition is always about giving permission. ³ Isn’t it patronizing and innaccurate to think of a software object as giving me, a human, permission to display tweets on a website? (I could just take a screenshot and bypass the API). Of course, allows you to also has a more general meaning (I discuss that in the last section). But in software docs, where many readers are reading in a foreign language or using a machine translator, the least ambiguous option is best.

“Lets you” is shorter

Maybe you find my previous arguments unconvincing. Besides, some software features really do configure permissions. Either way, lets you is still a better construction. The reason is undeniable: it’s shorter.

Good technical writing should be as short as possible. Semantically, the following sentences are essentially identical: ³

- The `authenticate` endpoint allows you to view resources according to your credentials.
+ The `authenticate` endpoint lets you view resources according to your credentials.

But lets you uses five fewer characters. If you can transmit the same meaning with less text, you should: boost signal, reduce noise.

In a single sentence, such an improvement is small and rather inconsequential. But small changes add up, and technical communicators should try to standardize quality at all levels.

I am not alone in this idea: the Google Style Guide also recommends lets over allows. ⁴

Alternatives

Instead of allows you to and other intermediaries, tailor your vocabulary and syntax to the goals of your text.

In task-based docs, front the action

In a doc that describes procedures, consider inverting your syntax. That is, place the result before the command. For example, a doc called “How to use Nginx” could have a phrase like this.

To stop the server, run nginx -s quit.

Beginning with an infinitive of purpose helps readers scan for what they want to do (since readers scan in an F-shaped pattern).

In references, put behavior before context

Descriptions in references should be spartan. For example, a doc called “Nginx CLI reference” might have something like this:

nginx -s quit

Stops the server

If it’s important to communicate goals, you could provide context in a second sentence. For example:

The OCR API processes a batch of images and detects common visual features. These groupings can serve as search filters for a large image database.

Use the imperative

This is often the simplest and most direct way to describe the purpose of a tool. For example, the Whatsapp doc quoted at the beginning now reads as follows:

Use the Forward feature to forward messages from an individual or group chat to another individual or group chat.

Some writer at Facebook also didn’t like allows you to!

But who cares about such a common and tiny phrase?

True, this issue is small in the grand scheme of things. Good docs won’t be spoiled by an allows you to (MDN is proof). But these details do matter if you think systematically about creating quality documentation. If allows you to creates an unnecessary intermediary between an actor and action, it also creates inaccuracy, and technical communicators should always Try to tell the truth. Even when it’s appropriate, shorter alternatives exist, and technical texts should be as simple as possible and no simpler.

It’s also true that the phrase is common. When it comes to language in ordinary life, I’m a descriptivist. And I must acknowledge that allows you to is a perfectly common expression, ⁵ very often used without any sub-text about giving permission. However, technical writing represents a highly constrained use of language, where brevity and clarity are more important than “naturalness.”

Avoid allows you to. This isn’t a big issue, but it’s an easy one to fix, and better is better.