active, passive, and ... commanding

[Karsten Wade]

Ah, my favorite part of documentation mailing lists, the grammar
debates. :)

This page ...

http://fedoraproject.org/wiki/DocsProject/StyleGuide/GeneralGuidelines

... provides guidelines on using active, passive, and a commanding
voice.  I'm personally not in full agreement with the recommendations,
and wanted to discuss this here, see what consensus we can reach.

In the "use active voice" camp, we generally avoid passive voice like
the plague.  A hallmark of the passive voice is the word 'will', as in,
"Click OK and then the page will change to blue."   Compare that to,
"Click OK and the page changes to blue."  The second is more
authoritative and assuring, and provides a context-in-time.  By that I
mean, it assumes the reader is following the directions in real time, in
which case, the screen is not going to eventually change to blue, it is
going to do it immediately in response to clicking OK.

Once you accept that, you quickly find that you never need the passive
voice.  Even to avoid awkward sentence structure.  If you want to say
that something "will happen", it either "is going to happen" or "might
happen."

Commanding voice seems to be about a more strongly worded version of
active voice.  I don't see a need for it, other than as part of
admonitions.  That is, we permit/suggest people are more commanding in
admonitions.

But the commanding voice examples such as, "You will click the OK
button," actually is more confusing than commanding.  It sounds like a
prediction of the future.  What happens if the user does not click OK?
The command is now false -- the user in the future ('will do') did not
in fact do the action.  Does not compute!  Circuits melting!  Thus, I
find the commanding voice to be self-contradictory and self-confusing.

My thinking is to clarify the voice section thus:

1. Active voice == good
 1.1 Examples of active voice
2. Passive voice == bad
 2.1 Examples of passive voice
  2.1.1 How to use a global search for the word 'will' to eliminate 80%
of your passive voice usage

Opinions? :)

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060710/7b52afd2/attachment.sig>