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/
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
