Use active voice in your documentation for happier readers

We know that writing technical content is important, and the way you write that content is even more important. It has to be accessible and easy to understand, which is why you need to use active voice.

This may be a fact well-known by technical writers, but if you’re a non-expert charged with creating some user documentation, you might be thinking, what the heck is active voice?! And how do I use it?

We’ll tell you in this article.

What is active voice?

Most sentences in English have a subject and a verb. The subject is who or what your sentence is about, and the verb describes an action or state of being.

Writing in the active voice means the subject is doing the action. The opposite is passive voice, when the subject is having the action done to them.

For example, ‘the dog [subject] chases the ball [object]’ is written in active voice. If we were to reorganise this sentence into passive voice, it would be ‘the ball [object] was chased by the dog [object].’ The latter is much more wordy, and slower to read, than the former.  

Image: Public Domain Pictures

For documentation purposes, active voice should be written in present tense (you are, rather than will be or were). It should also be written in the second person (‘you’, rather than ‘I’ or ‘they’).

If this all just sounds like a grammar lesson, that’s because it is! Better writing requires a basic understanding of grammar, because grammar allows us to structure our writing to make it readable for others.

Why is active voice important

When you use the active voice, your reader will comprehend the content of your sentence far more quickly than if they had to decode a longer sentence written in the passive voice. It reduces your word count by 10-15%, which is crucial for time and attention-strapped online users. Using active voice makes your documentation easier to read.

Active voice acknowledges that there is a subject with responsibility. Passive voice can be used to shift blame, as if there is no actor, and things happen of their own accord. Consider ‘There was an oil spill’, rather than ‘Black Shore Oil Company spilled oil’.

In the case of user documentation, you’re empowering your reader to complete the task at hand by using the active voice, instead of referring to a vague third party.

Large companies often have their own documentation style guides, and many suggest using active voice. It’s an industry standard.

Email marketing software company MailChimp recommends using active voice in their extensive style guides.

Cloud computing software company OpenStack tells its users to write their documentation in active voice.

These companies with two very different user bases (MailChimp is aimed at a large variety of non-technical users, from small business owners to email marketers, and OpenStack at software developers) advise their writers to use the active voice in their documentation.

It’s a universal method for making your writing more engaging, immediate and easy to understand.  

Why some people use passive voice

In days gone past, the passive voice was associated with sounding more ‘professional’ and when we wanted to sound more formal. The scientific community thought it made them sound more objective, and this has carried over into other types of writing.

Image: Public Domain Pictures

In academia, students are still taught to use the passive voice, which is a hard thing to unlearn. When everyone migrated to the web, the passive voice turned out to be much too cumbersome.

Passive voice is also much more ambiguous that active voice. Saying ‘A study was conducted on participants’ is more mysterious than simply saying ‘We conducted a study’. It places a layer of reserve between the writer of the study and those reading it. Occasionally, it can disguise some very sloppy practices.

It’s always preferable to be as clear as possible in your technical communication and on the web in general.

How to use active voice

While you can decide who is the subject of your writing every time you sit down at the keyboard, with user documentation, the subject is almost always going to be your user. You should aim to write your documentation in the active voice with the user as your subject, referring to them in the second tense.

Every time you write a piece of documentation, set aside time to review it to make sure it’s written in active voice.

Check for:

1. Present tense (‘Save your file’ rather than ‘having saved your file’)
2. Second tense (‘you’ rather than ‘they’, ‘we’ or ‘I’)
3. Focus on the subject (‘you open a new account’ rather than ‘a new account was opened’)
4. Delete unnecessary words
5. Imperatives telling the reader what to do (Eg ‘Click on the first menu option’)

Tools like the Hemingway App or Grammarly help you write in active voice by scanning your work and highlighting where you could make improvements, like using the active voice. These are free tools that will do wonders to improve your writing, making it more direct and concise. Grammarly have also written a fantastic article teaching you how to check for the passive voice. 

Imagine the user reading your technical content as though they are moving through a video game. Each action is directly connected to the next, and you have to describe each action as simply as possible.

Image: Flickr

Tell your user what to do in as few words as possible. It’s as though there really is a game-based pressure on them to accomplish their goal, or perhaps an enemy monster trying to destroy them.

When not to use active voice

There are some occasions when using active voice is not advised. This could be when:

• You’re focusing on the object (‘A message is sent out by the database’)
• An error message (‘A key may be missing from the form’)

If you use active voice in an error message, this may be perceived as accusatory by your users. Using the passive voice softens the tone.

Similarly, if you’re focus is actually on the object, then you should use passive voice to draw attention to that rather than the subject.

There may also be times when your writing would become overly complex if you were to force it into the active voice. In those cases, it’s okay to use the passive voice too.

Final remarks

The harder your writing is to understand, the more likely your readers are to give up on it.

That’s why the golden rule of technical writing, web writing, and writing in general, is to be as clear as possible in everything you write. In your writing process, edit your writing until you have removed any possibility of misinterpretation or ambiguity.

If this all sounds like a lot of work, that’s because it is. Good writing takes time and effort, but the good news is that, with practice, it will become like second nature for you.

Since writing is an art, rather than a science, there is always room for flexibility and deviating from the rulebook. You don’t always need to write in the active voice, but that will be the exception, rather than the norm.

KnowledgeOwl offers dedicated knowledge base software to help you write your best support documentation. Take us for a free spin today.