Secret ingredients to quality software


Tiny: Do you use active phrases? (No zombies please)

Last updated by Tiago Araujo on 21 Jun 2019 07:48 pm (about 2 years ago) See History

To get the most out of your communications, your writing should be compelling and direct. The best way to ensure this is to use active voice.

For example:

When the CD is inserted, a Windows dialog will be shown.

Figure: Bad Example - This example is using a passive voice, and does not address the reader or from the point of the subject (the software in this case).

When you insert a CD, Windows shows a dialog.

Figure: Good Example - This example uses the active voice to address the reader, and is more direct and engaging.

An easy way to tell if you're using the passive voice is to add "by zombies" after verb. If your sentence still make sense, you're using passive voice. 

The email was sent by zombies

Figure: Bad example - This sentence could be more engaging

Zombies sent the email 

Figure: Good example - Now that's a more engaging sentence

3 reasons you should avoid passive voice:

  1. Passive voice uses more words - in the figures above, the "Bad Example" uses 6 words whereas the "Good example" uses only 4
  2. It's less logical - instead of having the subject do something to the object, the object does something to the subject
  3. It's less clear - In the bad example above, you don't know who was acting until the end of the sentence, whereas in the good example, you know immediately.
Joanna FeelyJoanna Feely

We open source. This page is on GitHub