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 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
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
