emacs documentation: what's active voice, passive voice?

emacs documentation: what's active voice, passive voice?

[Xah Lee]

of interest.

• 〈What's Passive Voice? What's Aggresive Voice?〉
http://xahlee.org/Periodic_dosage_dir/bangu/active_voice_passive_voice.html

--------------------------------------------------
What's Passive Voice? What's Aggresive Voice?

Xah Lee, 2010-10-02

In writing, you know that there is passive voice and active voice,
right? And the writing style guilds tell us, that we should use active
voice. In the following sentences, can you tell which is active voice
and which is passive voice?

    * (1) At dawn the crowing of a rooster could be heard.
    * (2) There were a great number of dead leaves lying on the
ground.
    * (3) It was not long before she was very sorry that she had said
what she had.
    * (4) The reason that he left college was that his health became
impaired.

Take 5 min to answer before you read on.

The Language Log recently has a blog asking readers to identify
passive/active voice. (Apparantly, they've been beating this horse for
a while, but i only started to read Language Log last month.) Before i
tackle the question and post my redoubtable comment with implicit
offense at grammarians, i thought to myself: it's been some 17 years
when i read anything technical about passive/active voice in Struck &
White... so let me look into Wikipedia to refresh myself just so i
won't come out a fool.

So, my first stop is at: Passive voice. And WHAM! It is
incomprehensible, and to ME!? To understand the article well, i'll
have to delve into my brain and read it carefully about all the
“subject”, “verb”, “object”, “adjective”, “adverb”, “aux verb”, and
perhaps reacquaint myself with the evil “split infinitives”. Fuck
that. By my mastery of info age, i took the shortcut and went directly
to the article English passive voice instead. The article there is
still a bit dense, but i found the above 4 examples about passive
voice, quoted right from “Strunk & White”, except that 3 of them are
actually active voice! The source of this is from:

    * 〈50 Years of Stupid Grammar Advice〉 (2009-04-17) By Geoffrey K
Pullum. The Chronicle of Higher Education 55 (32): B15. chronicle.com

Quote:

    The Elements of Style does not deserve the enormous esteem in
which it is held by American college graduates. Its advice ranges from
limp platitudes to inconsistent nonsense. Its enormous influence has
not improved American students' grasp of English grammar; it has
significantly degraded it.

    ...

    What concerns me is that the bias against the passive is being
retailed by a pair of authors so grammatically clueless that they
don't know what is a passive construction and what isn't. Of the four
pairs of examples offered to show readers what to avoid and how to
correct it, a staggering three out of the four are mistaken diagnoses.
“At dawn the crowing of a rooster could be heard” is correctly
identified as a passive clause, but the other three are all
errors: ...

        * “There were a great number of dead leaves lying on the
ground” has no sign of the passive in it anywhere.
        * “It was not long before she was very sorry that she had said
what she had” also contains nothing that is even reminiscent of the
passive construction.
        * “The reason that he left college was that his health became
impaired” is presumably fingered as passive because of “impaired,” but
that's a mistake. It's an adjective here. “Become” doesn't allow a
following passive clause. (Notice, for example, that “A new edition
became issued by the publishers” is not grammatical.)

So here we are.

I pride myself as a good writer (n i'd like to think within top 100 on
this earth), albeit with unique usage and style. (See: The Writing
Style on XahLee.org.) I read “Strunk & White”'s The Elements of Style
in the early 1990s, i think twice, among quite a few other writing
guides and advices. I've seen countless advices for active voice in
the past 20 years, everywhere. For example, here's quote from GNU
Emacs Lisp Reference Manual: Documentation Tips. Quote:

    Write documentation strings in the active voice, not the passive,
and in the present tense, not the future. For instance, use “Return a
list containing A and B.” instead of “A list containing A and B will
be returned.”

Not until today, i realized, just how much i did not understand what
is Active voice and Passive voice, and when you look into this issue,
such as Wikipedia article on it, you see that it is quite technical.
Unless you have a good study of linguistics, you wouldn't understand
it. And of course, the common advices on “active” voice, even from
professional style guides, are just totally clueless.

Today, “passive voice” simply means sentences that do not sound
dynamic or in action. The word “passive” in “passive voice” just mean
the opposite of “aggresive”. So, if a sentence sounds lame, it is
passive voice! And, actually, for pop communication, i think i endorse
this interpretation; screw linguistic history.

Here's one of the article from Language Log about this issue:

    * 〈“Passive Voice” — 1397-2009 — R.I.P.〉 (2009-03-12) By Mark
Liberman. At: Language Log

--------------------------------------------------

PS for those who got it wrong, don't feel bad. Few people on this
earth can get it right, and most of them mob toilets at McDonalds.
Just be happy that we all understand split infinitives, at least.

 Xah ∑ xahlee.org ☄

Re: emacs documentation: what's active voice, passive voice?

[Uday Reddy]

On 10/3/2010 4:06 AM, Xah Lee wrote:

> The Language Log recently has a blog asking readers to identify
> passive/active voice. (Apparantly, they've been beating this horse for
> a while, but i only started to read Language Log last month.) Before i
> tackle the question and post my redoubtable comment with implicit
> offense at grammarians, i thought to myself: it's been some 17 years
> when i read anything technical about passive/active voice in Struck&
> White... so let me look into Wikipedia to refresh myself just so i
> won't come out a fool.

Gosh, for a while there, I thought Emacs had begun to complain about passive voice.  Heaven forbid!

>
>      * 〈50 Years of Stupid Grammar Advice〉 (2009-04-17) By Geoffrey K
> Pullum. The Chronicle of Higher Education 55 (32): B15. chronicle.com
>
> Quote:
>
>      The Elements of Style does not deserve the enormous esteem in
> which it is held by American college graduates. Its advice ranges from
> limp platitudes to inconsistent nonsense. Its enormous influence has
> not improved American students' grasp of English grammar; it has
> significantly degraded it.
>
>      ...
>
>      What concerns me is that the bias against the passive is being
> retailed by a pair of authors so grammatically clueless that they
> don't know what is a passive construction and what isn't. Of the four
> pairs of examples offered to show readers what to avoid and how to
> correct it, a staggering three out of the four are mistaken diagnoses.
> “At dawn the crowing of a rooster could be heard” is correctly
> identified as a passive clause, but the other three are all
> errors: ...

Pretty damning — or it would be if Strunk and White had actually claimed any of those were passive constructions. They don’t. Here’s how they introduce these examples: “Many a tame sentence of description or exposition can be made lively and emphatic by substituting a transitive in the active voice for some such perfunctory expression as there is, or could be heard.” (My link is to the online text of the Strunk-only 1918 edition, but the passage is unchanged in later editions.)

Now, Strunk and White themselves use the passive voice in that sentence, so one might say they are violating their own rules (though they’re not — they don’t say the passive may never be used, only that active constructions tend to be more forceful). But they don’t claim that their examples are all in the passive voice. Excessive deployment of the passive is only one of the weaknesses they discuss in this section. Their point is not only to urge the use of the active voice but to encourage the use of “active” transitive verbs rather than limp declarations of being. It’s sound advice: “dead leaves covered the ground” really is more forceful and better than “there were a great number of dead leaves lying on the ground.”

One can fairly complain that Strunk and White perceive the threat to good style as coming from only one direction. Consider their next section, in which they command, “Make definite assertions. Avoid tame, colorless, hesitating, non-committal language. Use the word not as a means of denial or in antithesis, never as a means of evasion.” “Denial,” “evasion,” “colorless” — these are tendentious terms. Someone who takes the authors’ advice too literally will always write fortissimo, without any understanding of the uses and virtues of the pianissimo. Irony, impartiality, subtlety, and negation do have a place in good writing. And bad prose can be Stentorian just as it can be anodyne, though admittedly most writers, especially in academia, err on the mushy side.

   --  The Elements of Bad Style?
       Posted on April 26th, 2009 by Daniel McCarthy	
       http://www.amconmag.com/mccarthy/2009/04/26/the-elements-of-bad-style/

I have no idea why the linguists have begun to stab each other.  But it looks like a good idea for Computer Scientists to stay out of it.

Cheers,
Uday

Re: emacs documentation: what's active voice, passive voice?

[Bruce Stephens]

Xah Lee <xahlee@gmail.com> writes:

[...]

> PS for those who got it wrong, don't feel bad. Few people on this
> earth can get it right, and most of them mob toilets at McDonalds.
> Just be happy that we all understand split infinitives, at least.

Of course, as regularly mentioned on Language Log, splitting infinitives
is (and always has been) fine in English.

Re: emacs documentation: what's active voice, passive voice?

[Russ P.]

On Oct 3, 4:14 am, Uday Reddy <uDOTsDOTre...@cs.bham.ac.uk> wrote:
> On 10/3/2010 4:06 AM, Xah Lee wrote:
>
> > The Language Log recently has a blog asking readers to identify
> > passive/active voice. (Apparantly, they've been beating this horse for
> > a while, but i only started to read Language Log last month.) Before i
> > tackle the question and post my redoubtable comment with implicit
> > offense at grammarians, i thought to myself: it's been some 17 years
> > when i read anything technical about passive/active voice in Struck&
> > White... so let me look into Wikipedia to refresh myself just so i
> > won't come out a fool.
>
> Gosh, for a while there, I thought Emacs had begun to complain about passive voice.  Heaven forbid!
>
>
>
>
>
> >      * 〈50 Years of Stupid Grammar Advice〉 (2009-04-17) By Geoffrey K
> > Pullum. The Chronicle of Higher Education 55 (32): B15. chronicle.com
>
> > Quote:
>
> >      The Elements of Style does not deserve the enormous esteem in
> > which it is held by American college graduates. Its advice ranges from
> > limp platitudes to inconsistent nonsense. Its enormous influence has
> > not improved American students' grasp of English grammar; it has
> > significantly degraded it.
>
> >      ...
>
> >      What concerns me is that the bias against the passive is being
> > retailed by a pair of authors so grammatically clueless that they
> > don't know what is a passive construction and what isn't. Of the four
> > pairs of examples offered to show readers what to avoid and how to
> > correct it, a staggering three out of the four are mistaken diagnoses.
> > “At dawn the crowing of a rooster could be heard” is correctly
> > identified as a passive clause, but the other three are all
> > errors: ...
>
> Pretty damning — or it would be if Strunk and White had actually claimed any of those were passive constructions. They don’t. Here’s how they introduce these examples: “Many a tame sentence of description or exposition can be made lively and emphatic by substituting a transitive in the active voice for some such perfunctory expression as there is, or could be heard.” (My link is to the online text of the Strunk-only 1918 edition, but the passage is unchanged in later editions.)
>
> Now, Strunk and White themselves use the passive voice in that sentence, so one might say they are violating their own rules (though they’re not — they don’t say the passive may never be used, only that active constructions tend to be more forceful). But they don’t claim that their examples are all in the passive voice. Excessive deployment of the passive is only one of the weaknesses they discuss in this section. Their point is not only to urge the use of the active voice but to encourage the use of “active” transitive verbs rather than limp declarations of being. It’s sound advice: “dead leaves covered the ground” really is more forceful and better than “there were a great number of dead leaves lying on the ground.”
>
> One can fairly complain that Strunk and White perceive the threat to good style as coming from only one direction. Consider their next section, in which they command, “Make definite assertions. Avoid tame, colorless, hesitating, non-committal language. Use the word not as a means of denial or in antithesis, never as a means of evasion.” “Denial,” “evasion,” “colorless” — these are tendentious terms. Someone who takes the authors’ advice too literally will always write fortissimo, without any understanding of the uses and virtues of the pianissimo. Irony, impartiality, subtlety, and negation do have a place in good writing. And bad prose can be Stentorian just as it can be anodyne, though admittedly most writers, especially in academia, err on the mushy side.
>
>    --  The Elements of Bad Style?
>        Posted on April 26th, 2009 by Daniel McCarthy    
>        http://www.amconmag.com/mccarthy/2009/04/26/the-elements-of-bad-style/
>
> I have no idea why the linguists have begun to stab each other.  But it looks like a good idea for Computer Scientists to stay out of it.
>
> Cheers,
> Uday

For technical writing, I favor active voice where appropriate, but in
some cases I think passive voice is preferable. Consider, for example,
"The parameters were perturbed, and the test was run again." I could
rewrite that in active voice as "We varied the parameters and ran the
test again." But what if there is no "we", only "I"? Then I would have
to write "I varied the parameters and ran the test again." That just
doesn't strike me as good style for a technical paper. The point is
not who did it but that it was done. What difference would it make if
a monkey did it, as long as he did it right?

Russ P.

Re: emacs documentation: what's active voice, passive voice?

[Jay Belanger]

> Then I would have to write "I varied the parameters and ran the test
> again." That just doesn't strike me as good style for a technical
> paper.

Why not?

> The point is not who did it but that it was done. What difference
> would it make if a monkey did it, as long as he did it right?

But you were talking about style, not content.

Re: emacs documentation: what's active voice, passive voice?

[David Kastrup]

Jay Belanger <jay.p.belanger@gmail.com> writes:

>> Then I would have to write "I varied the parameters and ran the test
>> again." That just doesn't strike me as good style for a technical
>> paper.
>
> Why not?

The next test run used a different set of parameters.

-- 
David Kastrup

Re: emacs documentation: what's active voice, passive voice?

[B. T. Raven]

Xah Lee wrote:
> of interest.
> 
> • 〈What's Passive Voice? What's Aggresive Voice?〉 
> http://xahlee.org/Periodic_dosage_dir/bangu/active_voice_passive_voice.html
> 
> 
> 
> 
> 
> 
> 
> -------------------------------------------------- What's Passive 
> Voice? What's Aggresive Voice?
> 
> Xah Lee, 2010-10-02
> 
> In writing, you know that there is passive voice and active voice, 
> right? And the writing style guilds tell us, that we should use 
> active voice. In the following sentences, can you tell which is 
> active voice and which is passive voice?
> 
> * (1) At dawn the crowing of a rooster could be heard. * (2) There 
> were a great number of dead leaves lying on the ground. * (3) It was 
> not long before she was very sorry that she had said what she had. * 
> (4) The reason that he left college was that his health became 
> impaired.
> 
> Take 5 min to answer before you read on.
> 
> The Language Log recently has a blog asking readers to identify 
> passive/active voice. (Apparantly, they've been beating this horse 
> for a while, but i only started to read Language Log last month.) 
> Before i tackle the question and post my redoubtable comment with 
> implicit offense at grammarians, i thought to myself: it's been some 
> 17 years when i read anything technical about passive/active voice in
> Struck & White... so let me look into Wikipedia to refresh myself 
> just so i won't come out a fool.
> 
> So, my first stop is at: Passive voice. And WHAM! It is 
> incomprehensible, and to ME!? To understand the article well, i'll 
> have to delve into my brain and read it carefully about all the 
> “subject”, “verb”, “object”, “adjective”, “adverb”, “aux verb”, and 
> perhaps reacquaint myself with the evil “split infinitives”. Fuck 
> that. By my mastery of info age, i took the shortcut and went 
> directly to the article English passive voice instead. The article 
> there is still a bit dense, but i found the above 4 examples about 
> passive voice, quoted right from “Strunk & White”, except that 3 of 
> them are actually active voice! The source of this is from:
> 
> * 〈50 Years of Stupid Grammar Advice〉 (2009-04-17) By Geoffrey K 
> Pullum. The Chronicle of Higher Education 55 (32): B15. chronicle.com
> 
> 
> 
> 
> 
> 
> 
> Quote:
> 
> The Elements of Style does not deserve the enormous esteem in which 
> it is held by American college graduates. Its advice ranges from limp
>  platitudes to inconsistent nonsense. Its enormous influence has not 
> improved American students' grasp of English grammar; it has 
> significantly degraded it.
> 
> ...
> 
> What concerns me is that the bias against the passive is being 
> retailed by a pair of authors so grammatically clueless that they 
> don't know what is a passive construction and what isn't. Of the four
>  pairs of examples offered to show readers what to avoid and how to 
> correct it, a staggering three out of the four are mistaken 
> diagnoses. “At dawn the crowing of a rooster could be heard” is 
> correctly identified as a passive clause, but the other three are all
>  errors: ...
> 
> * “There were a great number of dead leaves lying on the ground” has 
> no sign of the passive in it anywhere. * “It was not long before she 
> was very sorry that she had said what she had” also contains nothing 
> that is even reminiscent of the passive construction. * “The reason 
> that he left college was that his health became impaired” is 
> presumably fingered as passive because of “impaired,” but that's a 
> mistake. It's an adjective here. “Become” doesn't allow a following 
> passive clause. (Notice, for example, that “A new edition became 
> issued by the publishers” is not grammatical.)

True, but this is not a clear cut case. As in computer programming so
with grammar: it's a lot like nailing jelly to a tree. It's not invalid
to consider "to become" as the inchoative aspect of the verb "to be."
Adjectives derived from participles are infected with passivity from the
get-go.

> 
> So here we are.


Within the top 100 on the planet!!?? In the English language?
The following constellated words, phrases and clauses are either
erroneous or at least infelicities of style. You could look it up.

> 
> I pride myself **as a** [on being a]good writer (**n** [and] **i'd** [I'd] like to think 
> within [the] top 100 on this earth), albeit [one] with unique usage and 
> style. (See: The Writing Style on XahLee.org.) I read “Strunk & 
> White”'s The Elements of Style in the early 1990s,

Either no quotes around authors' names or at least 's inside quotes.
_The Elements of Style_ [title emphasized]

 **i** [this
> Cummingsesque cutsiness is inappropriate except on Twitter] **i** [I] think 
> twice, among quite a few other writing guides and **advices** [not 
> plural in English without being somehow qualified]. I've seen 
> countless **advices** for active voice in the past 20 years, 
> everywhere. For example, here's quote from GNU Emacs Lisp Reference 
> Manual: Documentation Tips. Quote:
> 
> Write documentation strings in the active voice, not the passive, and
>  in the present tense, not the future. For instance, use “Return a 
> list containing A and B.” instead of “A list containing A and B will
>  be returned.”

As usual, sound advice from the Emacs developers.

> 
> Not until today, **i** realized, just how much **i** did not 
> understand what is Active voice and Passive voice, and when you look 
> into this issue, **such as** [by for example reading]a Wikipedia 
> article on it, you see that it is quite technical. Unless you have a 
> **good study** [pretty muddy for something: understanding, 
> background??]  of linguistics, you **wouldn't** [violates sequence of
>  tenses] understand it. And of course, the common **advices** on 
> [the] “active” voice, even from professional style guides, are just 
> totally **clueless.** [too slangy for incompetent, impertinent, 
> misleading, or something]
> 
> Today, “passive voice” simply means sentences that do not sound 
> dynamic or in action. The word “passive” in “passive voice” just mean
>  the opposite of “aggresive”. So, if a sentence sounds **lame** 
> [generically pejorative but of uncertain denotation], it is passive 
> voice! [Maybe in the semi-private language of some spritually inbred
>  subculture] And, actually, for **pop** [popular?? informal??] 
> communication, **i** think **i** endorse this interpretation; 
> **screw** [too slangy for "deprecate," or better, passively,
> "linguistic history should be deprecated," NOT!] linguistic history.

Wrong, wrong, wrong! In the passive voice, the original active voice
object becomes the subject and the verb is converted to copula plus
participle (in English).

> 
> Here's one of the article from Language Log about this issue:
> 
> * 〈“Passive Voice” — 1397-2009 — R.I.P.〉 (2009-03-12) By Mark 
> Liberman. At: Language Log

Unde annus ille 1397timus? Liberman eum e petaso extraxit, nonne?
Sorry, couldn't resist.

> 
> --------------------------------------------------
> 
> PS for those who got it wrong, don't feel bad. Few people on this 
> earth can get it right, and most of them **mob** [just a typo, I 
> realize, but the effect is ridiculous] toilets at McDonald[']s. [or 
> McDonalds', i.e. possesive, not plural] Just be happy that we all 
> understand split infinitives, at least.

Yes, by their very nature, infinitives are split in English: "to love"
vs. "amare." There's no room in the atom "amare" to insert anything.
Still, good writers know how to imitate Latinate style, when
appropriate. Jonathan Swift, for example, a consummate stylist, used few
if any split infinitives.

Ed

> 
> Xah ∑ xahlee.org ☄

Re: emacs documentation: what's active voice, passive voice?

[Russ P.]

On Oct 3, 1:50 pm, David Kastrup <d...@gnu.org> wrote:
> Jay Belanger <jay.p.belan...@gmail.com> writes:
> >> Then I would have to write "I varied the parameters and ran the test
> >> again." That just doesn't strike me as good style for a technical
> >> paper.
>
> > Why not?
>
> The next test run used a different set of parameters.

Maybe, but I'm not sure. It seems to me that you've
anthropomorphisized the test run. The test run does not "use" the
parameters. The experimenter does. You could say, "The next test run
had a different set of parameters." But then you're back to passive
voice, or so it seems to me -- but what do I know?

Re: emacs documentation: what's active voice, passive voice?

[David Kastrup]

"B. T. Raven" <nihil@nihilo.net> writes:

> Yes, by their very nature, infinitives are split in English: "to love"
> vs. "amare." There's no room in the atom "amare" to insert anything.

So where do you split the infinitive in "Don't make me cry"?  I was not
aware that "to" was a part of the infinitive proper.

-- 
David Kastrup

Re: emacs documentation: what's active voice, passive voice?

[Alan Mackenzie]

> For technical writing, I favor active voice where appropriate, but in
> some cases I think passive voice is preferable. Consider, for example,
> "The parameters were perturbed, and the test was run again." I could
> rewrite that in active voice as "We varied the parameters and ran the
> test again." But what if there is no "we", only "I"? Then I would have
> to write "I varied the parameters and ran the test again." That just
> doesn't strike me as good style for a technical paper. The point is not
> who did it but that it was done. What difference would it make if a
> monkey did it, as long as he did it right?

Maybe the parameters might be less perturbed at being varied by a monkey
than by your good self.  Who knows?

> Russ P.

-- 
Alan Mackenzie (Nuremberg, Germany).
;-)

Re: emacs documentation: what's active voice, passive voice?

[Russ P.]

On Oct 4, 11:48 am, Alan Mackenzie <a...@muc.de> wrote:
> > For technical writing, I favor active voice where appropriate, but in
> > some cases I think passive voice is preferable. Consider, for example,
> > "The parameters were perturbed, and the test was run again." I could
> > rewrite that in active voice as "We varied the parameters and ran the
> > test again." But what if there is no "we", only "I"? Then I would have
> > to write "I varied the parameters and ran the test again." That just
> > doesn't strike me as good style for a technical paper. The point is not
> > who did it but that it was done. What difference would it make if a
> > monkey did it, as long as he did it right?
>
> Maybe the parameters might be less perturbed at being varied by a monkey
> than by your good self.  Who knows?
>
> > Russ P.
>
> --
> Alan Mackenzie (Nuremberg, Germany).
> ;-)

I realize that you are kidding, but to perturb a parameter means to
vary it slightly.

http://en.wikipedia.org/wiki/Perturbation_theory

Re: emacs documentation: what's active voice, passive voice?

[B. T. Raven]

David Kastrup wrote:
> "B. T. Raven" <nihil@nihilo.net> writes:
> 
>> Yes, by their very nature, infinitives are split in English: "to love"
>> vs. "amare." There's no room in the atom "amare" to insert anything.
> 
> So where do you split the infinitive in "Don't make me cry"?  I was not
> aware that "to" was a part of the infinitive proper.
> 

Some say it is "the full infinitive" and some say it ain't. Some even
say there is no infinitive in English, only the plain form that also
serves for imperative and subjunctive (e.g. be that as it may). All
these categories tend to morph into each other as for example in "Don't
try to make me laugh" and "don't try and make me laugh" where, in the
second example "make" is at least half way toward being an imperative.
Already far afield from Emacs or even Emacs documentation but I didn't
start it:

http://en.wikipedia.org/wiki/Infinitive

Re: emacs documentation: what's active voice, passive voice?

[David Combs]

In article <cMWdnVIcw6z-PjfRnZ2dnUVZ_uadnZ2d@sysmatrix.net>,
B. T. Raven <nihil@nihilo.net> wrote:
>David Kastrup wrote:
>> "B. T. Raven" <nihil@nihilo.net> writes:
>> 
>>> Yes, by their very nature, infinitives are split in English: "to love"
>>> vs. "amare." There's no room in the atom "amare" to insert anything.
>> 
>> So where do you split the infinitive in "Don't make me cry"?  I was not
>> aware that "to" was a part of the infinitive proper.
>> 
>
>Some say it is "the full infinitive" and some say it ain't. Some even
>say there is no infinitive in English, only the plain form that also
>serves for imperative and subjunctive (e.g. be that as it may). All
                                             ^^            ^^^


"Be" is (of course?) in the subjunctive.  What about the "may"?


Thanks!

David

Re: emacs documentation: what's active voice, passive voice?

[Stefan Monnier]

> But if you preturb a sleeping dog (or rattlesnake), you

Gods don't sleep, do they?


        Stefan

Re: emacs documentation: what's active voice, passive voice?

[Pascal J. Bourguignon]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> But if you preturb a sleeping dog (or rattlesnake), you
>
> Gods don't sleep, do they?

No, but ours got some rest on the seventh day.

-- 
__Pascal Bourguignon__                     http://www.informatimago.com/
A bad day in () is better than a good day in {}.

RE: emacs documentation: what's active voice, passive voice?

[Drew Adams]

> For technical writing, I favor active voice where
> appropriate, but in some cases I think passive voice is
> preferable. Consider, for example, "The parameters were
> perturbed, and the test was run again." I could
> rewrite that in active voice as "We varied the parameters 
> and ran the test again." But what if there is no "we",
> only "I"? Then I would have to write "I varied the
> parameters and ran the test again." That just
> doesn't strike me as good style for a technical paper. The 
> point is not who did it but that it was done. What
> difference would it make if a monkey did it, as long as he
> did it right?

Indeed.

There is a lot of misunderstanding about the passive voice and where, when, and
whether to use it.  Some people learn grammar catechism in school, taking away
the idea that banishing the passive voice will offer them a royal road to
writing clearly.

There is no royal road to writing, like Math.  To write better, read more.
Read, re-read, re-re-read, and read better what you've written (and
rewritten...).

This will help wrt the passive voice:
http://www.unc.edu/depts/wcweb/handouts/passivevoice.html

Re: emacs documentation: what's active voice, passive voice?

[Sean Sieger]

    There is no royal road to writing, like Math.  To write better, read more.
    Read, re-read, re-re-read, and read better what you've written (and
    rewritten...).

Right?  

I always thought `reading is miswriting and writing is misreading'
instructive.

Re: emacs documentation: what's active voice, passive voice?

[ken]

On 12/09/2010 08:16 PM Sean Sieger wrote:
>     There is no royal road to writing, like Math.  To write better, read more.
>     Read, re-read, re-re-read, and read better what you've written (and
>     rewritten...).
> 
> Right?  
> 
> I always thought `reading is miswriting and writing is misreading'
> instructive.

Good advice.  And it applies to a lot more technical documentation than
just what's done for emacs.

There's a very old saying among writers: Writing is rewriting.  Yeah,
that means more time and work than just dashing off a first draft.  But
the benefits are worth it.

One technique for better documentation is to give your first draft to a
newbie and have him/her work from it.  That newb will notice any holes
or ambiguities and other failures in the text; these are then added into
the doc.  This amended doc would then be passed on to another newb and
the process repeats repeats until a newb has no more questions or
failures.  A wiki is a good platform for this kind of process.