Grammar for technical writers

Many people, regardless of how well-read they are, struggle to understand grammar. For example, your school may not have taught grammar. Worse still, grammar doesn't seem to matter much in real life because most of us follow the basic grammar rules without thinking about why. Sometimes, you can even use incorrect grammar and as long as you're clear, people will probably understand what you mean.

In writing, readers can "read past" most bad grammar by making assumptions about what you meant to write, and that's a problem. The goal of documentation isn't to approximate the general idea of how something works. Technical writing is about precision, and proper and appropriate grammar can make your writing definitive and clear.

Present tense

When you write about something happening right now, it's the present tense. The present tense conveys that information is current and not expected to change in the near future. For example, this is a present tense description of a feature in a made-up application called WidgetFactory:

Two-factor authentication (2FA) is enabled by default.

That makes sense and the information it conveys is clear. But as a technical author, it's easy to think too literally about the state of technology. For instance, when the author actually typed that sentence, 2FA strictly wasn't enabled, because the future reader hadn't installed WidgetFactory yet.

You might argue that the future tense is more appropriate, because if a reader hasn't installed WidgetFactory at the time of reading the documentation, all discovery of WidgetFactory's features are in the future. But imagine the same description written in the future tense:

WidgetFactory will have two-factor authentication (2FA) enabled by default.

It's still accurate, but it's a lot less emphatic. The reader might rightfully wonder when will WidgetFactory have 2FA enabled? Today, or a year from now? Is 2FA a feature available in WidgetFactory today, or is it something users are waiting on?

These questions only exist when a sentence is written in the future tense. The present tense answers them implicitly.

The present tense keeps your reader engaged by bringing the lesson you're trying to teach into the current moment. In the present tense, your lessons aren't something that the reader will learn sometime far from now; they're things the reader is learning now.

I recommend you strike the word "will" from your writing. Doing so takes practice, and obviously there's always an exception for a "corner case." Not as often as you think, though! Notice how I could have written "there will always be an exception," but phrased it in the present tense instead?

Past tense

Past tense describes an event that happened before the present moment. In technical documentation, the past tense is important because it helps you assert that something has already happened, and that no further action is required. For example:

Login with password authentication was deprecated in version 2.0, so log in with the secret token you created during installation.

This sentence conveys that one thing was deprecated in a specific software version, and that the user has already created the new thing they need to continue. All of this could have been expressed differently using the present tense:

Login with password authentication is deprecated, so log in with your secret token.

It's a perfectly valid sentence and seems to convey the same information, but it could generate new questions. Is password authentication deprecated in the version of WidgetFactory I'm running? What if I'm reading the wrong version of the documentation? What secret token? Did I create a secret token? Those questions get answered implicitly by using the past tense.

Pluperfect or past perfect

The pluperfect tense, also called past perfect, adds even greater precision to the past tense. In the pluperfect tense, you describe an action that not only happened in the past, but was definitively completed prior to some specific time. This allows you to answer even more questions through careful wording.

Good: Full-disk encryption has been implemented since version 11, so all data storage methods in WidgetFactory are compliant with the Omega Directive.

In one sentence, you assure the reader that as long as they are running version 11 or greater, then their data storage is fully compliant with Omega Directive (an imaginary security protocol). Once again, you can attempt to convey similar data with a different verb tense:

Bad: Full-disk encryption is enabled in WidgetFactory, so data storage is compliant with the Omega Directive.

This assures the reader that a feature is enabled, but it doesn't specify when the feature (which is often hard to detect without looking for it specifically) actually appeared. It's not wrong or even confusing - it's just not as helpful as it is when written in the pluperfect tense.

Verb tenses make all the difference

Sentences are made up of words, and grammar describes the words you choose and how you arrange them within a sentence. In human language, there's a difference between what you say and how you say it. The words you use in your technical writing influences what your reader does with the information you're trying to impart, so choose wisely when conveying information. Through careful use of verb tenses, you can convey data more efficiently and clearly than ever before.