Cleaning Up Your Sentences

Using two actors

I follow a simple rule when I'm writing technical documentation: There are only two actors , the product and the user. I attribute all actions that I describe to one of these two actors.

You'll find that by always writing with the idea that either the product or user is doing something, you'll avoid ambiguities and passives. Passive sentences tend to make your sentences longer than they need to be. Here are some examples of writing using only two actors:

original: The file is saved.
revision: The program saves the file.
original: The Settings dialog appears when the Open button is clicked.
revision: The Settings dialog appears when you click the Open button.
original: The custom colors are defined manually.
revision: You define the custom colors.