Use Active Voice
Why Use Active Voice?
Active voice makes the performer of the action (usually the reader or user) the subject of the sentence.
Passive voice makes the recipient of the action (not the performer) the subject of the sentence.
When compared to passive-voice sentences, active-voice sentences are:
more engaging
less complicated
less wordy
easier to understand
With active voice, you can distinguish the actions and responses of the user from those of the technology.
Example
Beginning users look for specific calls to action in procedures. Active voice makes this clear.
Consider if you write a step that reads "The service can be restarted".
As written, this sentence reads as a consideration or a possibility, not an instruction. If the user skips this step due to this confusion, the rest of the tutorial might fail.
If you write "Restart the service", you remove all doubt. It saves the tutorial. This also clarifies that the user restarts the service.
In some systems, a service might restart itself after a failure. Active voice distinguishes between situations when a service acts and a user needs to act. "Restart the server" leaves no confusion over who performs the action: the user.
Use (active) | Avoid (passive) |
|---|---|
After you install the software, start the computer. | After the software has been installed, the computer can be started. |
Click OK to save the configuration. | The configuration is saved when the OK button is clicked. |
Create a server. | A server is created by you. |
MongoDB products and services solve your business problems. | Your business problems are solved by MongoDB products and services. |
When Do You Use Passive Voice?
You can use passive voice when using active voice:
Sounds like you're blaming the user. For example, you can use passive voice in an error message or troubleshooting content when the active subject is the user.
Makes the sentence wordy or awkward.
Would emphasize the performer when you don't know the performer of action or you want to de-emphasize the performer in favor the object on which the action is performed.
Acceptable (passive) | Avoid (active) | Why? |
|---|---|---|
If the build fails, the flavor might have been omitted. | If the build fails, you probably omitted the flavor. | The active voice blames the user. |
A flag was set incorrectly. | You set the flag incorrectly. | The active voice blames the user. |
Account owners can't be assigned additional roles, and their access can't be restricted. | Administrators can't assign account owners additional roles, and they can't restrict the access of account owners. | In this context, the object, account owners, is more important than the actor, administrators. |