active, passive, and ... commanding

Paul W. Frields stickster at gmail.com
Mon Jul 10 20:31:43 UTC 2006


On Mon, 2006-07-10 at 08:54 -0700, Karsten Wade wrote:
> 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? :)

+1.

Commanding voice is also excessively wordy:  "You will click the OK
button" not only can become untrue (if the user fails to follow
instructions), but is more concisely stated "Click the OK button."

The active voice also suffers under excessive gerund usage.  Wherever
you can, avoid using the gerund ("-ing") form of verbs, since they
generally weaken the sentence.  I myself am guilty of this constantly,
so I tend to grep 'ing[^a-z]' to find those problems.  (I also suffer
from excessive "will" usage, but I two tsp. of Karsten's magic 'C-s
will' syrup as a remedy.)

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
     Fedora Project Board: http://www.fedoraproject.org/wiki/Board
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
-------------- 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/ce13cecb/attachment.sig>


More information about the fedora-docs-list mailing list