As an editor and author, passive voice in technical documentation makes me cringe. It pays to be explicit. We coach all of our authors on active voice.
But I am not sure these ideas belong on this list. A pull request for places where resolving passive voice makes documentation less ambiguous seems like a better approach to me. If there are enough examples, perhaps we can revisit. -bt On Sat, Aug 3, 2019 at 11:28 PM Christopher Keele <[email protected]> wrote: > While this is an interesting thought, I'm not convinced it makes sense to > adopt as a practice. Citing the same reference you provide: > > When deciding between using Active or Passive Voice, ask the question: “Is >> it an advantage for the reader to know the performer of the action?” >> If the answer is Yes, use Active Voice. If the answer is No, use Passive >> Voice. > > > Consider the contexts in which a function's documentation may be consulted: > > - Clicking a link in a forum to the doc site > - Intellisense pop-up on hover > - Searching the doc site for a function > - Within a REPL > - Copy-pasted into a thread > > > In these contexts, the actual "performer" of the action--in the sense of > both whom the caller is, and who is running the program that invokes the > caller, can be very varied. Passive voice is useful in its anonymity about > the caller, and trying to be more specific seems to me like it would only > confuse most snippets. > > -- > You received this message because you are subscribed to the Google Groups > "elixir-lang-core" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/elixir-lang-core/edec2a8b-24b6-4750-9928-688315856e54%40googlegroups.com > <https://groups.google.com/d/msgid/elixir-lang-core/edec2a8b-24b6-4750-9928-688315856e54%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- Regards, Bruce Tate CEO <https://bowtie.mailbutler.io/tracking/hit/f8218219-d2a8-4de4-9fef-1cdde6e723f6/c7c97460-016e-45fb-a4ab-0a70318c7b97> Groxio, LLC. 512.799.9366 [email protected] grox.io -- You received this message because you are subscribed to the Google Groups "elixir-lang-core" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAFXvW-4n9J1t95%3DMUByLp6_9aXNFCdoCu6tSjg%2B8RoJtOMeL_w%40mail.gmail.com.
