November 6th, 2007


passive voice?

Okay, so I'm writing a requirements document that I want to be SCANNABLE. At one point I write this:

Wire should be shown using thin lines.
Shielded wire should include color designations.
References should be shown in side boxes.
Block diagrams should be organized to minimize bending of lines.
Switches should be shown in their off state.

Then I remember that voice in the back of my head saying that passive voice is always teh bad. So I re-write it.

Show wire with thin lines.
Include color designations of shielded wire.
Use side boxes for references.
Organize block diagrams to minimize the bending of lines.
Show switches in their off state.

Now, the second bit there uses fewer words and sounds more nice and direct. But the first bit moves the most important, most-likely-to-be-scanned word to the front. This is for engineers. They do not like to read. Say they're wondering how to show shielded wires... they might like the first list better, because it's got a glaring sentence that starts, 'Shielded Wires'.