4 ms·

All great advice. Except for “avoid passive”. It’s a part of the toolbox that changes the perspective on an action. “The pull request got merged” vs. “The mai

All great advice. Except for “avoid passive”. It’s a part of the toolbox that changes the perspective on an action. “The pull request got merged” vs. “The maintainer merged the pull request”. If i want to talk about the new feature that gets implemented by the pull request, then I mislead the reader by emphasizing the maintainer, rather than the pull request. The passive also allows you to choose whether you want to call out the source of an action. “The pull request got merged by the maintainer.” Yes, you can misuse it to fudge responsibility, but you don’t need the passive to do that.

medstrom 3y ago
"They merged the pull request" sounds fine to me.
- coldtea 3y ago
  As the parent notes though, "the passive also allows you to choose whether you want to call out the source of an action", while "they merged the pull request" does not.
  - medstrom 3y ago
    That part, I do not get. Do they mean it permits a rewrite? But all sentences do.
    - coldtea 3y ago
      They mean it allows you to not point out who did the merge. If the PR introduced a BUG or was a bad choice to merge it, you might not want to use an active form, because then you have to say who did it (for example, in a report), to protect them, or to not appear like you're pointing fingers. The passive voice allows you to state the fact that the commit was merged, without mentioning anybody. "John/Jil merged the pull request" vs "The pull request was merged" - you can chose whether you want to include "by John/Jil" or not.
- kd5bjo 3y ago
  In context, though, the passive version can sometimes make for smoother reading. My general rule of thumb is that each sentence should establish context at the beginning by referring to the preceding material and then introduce its new idea at the end— Whether it’s best to start with the maintainer or the pull request depends on which of those you’ve already been discussing. (I didn’t come up with this idea, but I unfortunately can’t remember where it came from)
  - svat 3y ago
    Possibly from here? * The Science of Scientific Writing (1990) by George Gopen and Judith Swan: https://web.archive.org/web/20240120063715/https://www.americanscientist.org/blog/the-long-view/the-science-of-scientific-writing https://web.archive.org/web/20240120063715/https://www.ameri... They say: > In our experience, the misplacement of old and new information turns out to be the No. 1 problem in American professional writing today. […] Put in the topic position [the beginning of the sentence] the old information that links backward; put in the stress position [the end of the sentence] the new information you want the reader to emphasize. It's a useful article, that I also mentioned in this answer: https://academia.stackexchange.com/questions/85286/why-do-researchers-sometimes-use-extremely-complicated-english-sentences-to-conv/85472#85472:~:text=The%20other%20article%20(The%20Science%20of%20Scientific%20Writing https://academia.stackexchange.com/questions/85286/why-do-re... — see also this video https://www.youtube.com/watch?v=jLPCdDp_LE0 https://www.youtube.com/watch?v=jLPCdDp_LE0 of Judy Swan, one of the co-authors (the accompanying handout is https://web.archive.org/web/20170331212200/https://www.cmu.edu/student-org/pcr/media-files/pcr-sessions/swan_summary.pdf https://web.archive.org/web/20170331212200/https://www.cmu.e...).
KineticLensman 3y ago
I was once caught in a contractual dispute that occurred because the author used passive. The contract basically said 'X will be done' without identifying whether the customer or contractor was expected to do X. Unfortunately this wasn't spotted until the contract was in place. If you must use passive in situations like these, please at least identify the agent, e.g. "X will be done by Y". Oy just use the shorter, explicit alternative: " X will do Y"
- ripe 3y ago
  > Unfortunately this wasn't spotted until the contract was in place. Sorry, couldn't resist pointing out this use of the passive voice.
  - KineticLensman 3y ago
    ha! In my defence I was demonstrating the way that passive voice can also be used to obscure responsibility after the event, as in "mistakes were made"

medstrom 3y ago

"They merged the pull request" sounds fine to me.

coldtea 3y ago
As the parent notes though, "the passive also allows you to choose whether you want to call out the source of an action", while "they merged the pull request" does not.
- medstrom 3y ago
  That part, I do not get. Do they mean it permits a rewrite? But all sentences do.
  - coldtea 3y ago
    They mean it allows you to not point out who did the merge. If the PR introduced a BUG or was a bad choice to merge it, you might not want to use an active form, because then you have to say who did it (for example, in a report), to protect them, or to not appear like you're pointing fingers. The passive voice allows you to state the fact that the commit was merged, without mentioning anybody. "John/Jil merged the pull request" vs "The pull request was merged" - you can chose whether you want to include "by John/Jil" or not.
kd5bjo 3y ago
In context, though, the passive version can sometimes make for smoother reading. My general rule of thumb is that each sentence should establish context at the beginning by referring to the preceding material and then introduce its new idea at the end— Whether it’s best to start with the maintainer or the pull request depends on which of those you’ve already been discussing. (I didn’t come up with this idea, but I unfortunately can’t remember where it came from)
- svat 3y ago
  Possibly from here? * The Science of Scientific Writing (1990) by George Gopen and Judith Swan: https://web.archive.org/web/20240120063715/https://www.americanscientist.org/blog/the-long-view/the-science-of-scientific-writing https://web.archive.org/web/20240120063715/https://www.ameri... They say: > In our experience, the misplacement of old and new information turns out to be the No. 1 problem in American professional writing today. […] Put in the topic position [the beginning of the sentence] the old information that links backward; put in the stress position [the end of the sentence] the new information you want the reader to emphasize. It's a useful article, that I also mentioned in this answer: https://academia.stackexchange.com/questions/85286/why-do-researchers-sometimes-use-extremely-complicated-english-sentences-to-conv/85472#85472:~:text=The%20other%20article%20(The%20Science%20of%20Scientific%20Writing https://academia.stackexchange.com/questions/85286/why-do-re... — see also this video https://www.youtube.com/watch?v=jLPCdDp_LE0 https://www.youtube.com/watch?v=jLPCdDp_LE0 of Judy Swan, one of the co-authors (the accompanying handout is https://web.archive.org/web/20170331212200/https://www.cmu.edu/student-org/pcr/media-files/pcr-sessions/swan_summary.pdf https://web.archive.org/web/20170331212200/https://www.cmu.e...).

KineticLensman 3y ago

I was once caught in a contractual dispute that occurred because the author used passive. The contract basically said 'X will be done' without identifying whether the customer or contractor was expected to do X. Unfortunately this wasn't spotted until the contract was in place. If you must use passive in situations like these, please at least identify the agent, e.g. "X will be done by Y". Oy just use the shorter, explicit alternative: " X will do Y"

ripe 3y ago
> Unfortunately this wasn't spotted until the contract was in place. Sorry, couldn't resist pointing out this use of the passive voice.
- KineticLensman 3y ago
  ha! In my defence I was demonstrating the way that passive voice can also be used to obscure responsibility after the event, as in "mistakes were made"