[Proposal] Using the active voice in the documentation
37 views
Skip to first unread message
hassan shaikley
Aug 2, 2019, 5:57:13 PM8/2/19
to elixir-lang-core
Hey all,
The docs are sometimes written with the passive voice when IMO they would be easier to read in the active voice.
An example from the Agent docs:
https://github.com/elixir-lang/elixir/compare/master...hassanshaikley:agent-docs-imo?expand=1
The definitions of the active and the passive voice from:
The docs are sometimes written with the passive voice when IMO they would be easier to read in the active voice.
An example from the Agent docs:
https://github.com/elixir-lang/elixir/compare/master...hassanshaikley:agent-docs-imo?expand=1
Relevant piece on when to use the Active vs Passive voice in documentation by Daphne Watson:
The definitions of the active and the passive voice from:
https://www.reddit.com/r/explainlikeimfive/comments/rpr2q/eli5_active_voice_vs_passive_voice/c47n837?utm_source=share&utm_medium=web2x
Examples from:
In the active voice, the subject of the sentence is the thing that's doing the action (the student, in your case). In passive voice, the subject is the recipient of the action (the book). As for the difference, well, read them - don't they sound different? As you picture what's happening, doesn't your mind visualize it differently?
Examples from:
https://writing.wisc.edu/handbook/style/ccs_activevoice/
I would love to hear what y'all think!
Passive: It was earlier demonstrated that heart attacks can be caused by high stress.
Active: Researchers earlier showed that high stress can cause heart attacks.
I would love to hear what y'all think!
damien krotkine
Aug 3, 2019, 4:42:43 PM8/3/19
to elixir-lang-core
Hi,
I’m respectfully not convinced by your example. The first change seems wrong to me: processes don’t *need* to store state. They don’t have any needs, wills, regrets or feelings. It’s the developer that has a need to store state. The change seems inappropriate.
The second diff actually changes the meaning of the sentence IMO. It looks like it provides two things: an implementation and an API, as if the API wasn’t part of the implementation.
I’m not convinced, it would make the docs less precise and harder to understand. My 2 cents of course :)
I’m respectfully not convinced by your example. The first change seems wrong to me: processes don’t *need* to store state. They don’t have any needs, wills, regrets or feelings. It’s the developer that has a need to store state. The change seems inappropriate.
The second diff actually changes the meaning of the sentence IMO. It looks like it provides two things: an implementation and an API, as if the API wasn’t part of the implementation.
I’m not convinced, it would make the docs less precise and harder to understand. My 2 cents of course :)
Lance Halvorsen
Aug 3, 2019, 5:32:11 PM8/3/19
to elixir-l...@googlegroups.com
Personally, I dislike the passive voice, and I do what I can to eliminate it in my writing. To my mind, though, we should make only the smallest possible edits to transform passive into active voice. Anything more runs the risk of changing the meaning.
With the Agent example Hassan provided:
The `Agent` module provides a basic server implementation that allows state to be retrieved and updated via a simple API.
I would simply make the subject of the dependent clause explicit, like this:
The `Agent` module provides a basic server implementation that allows us to retrieve and update state via a simple API.
The result is shorter and more direct, and the meaning is exactly the same.
--
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 elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/53ebe2d5-0cd2-4a31-88f6-e0aaf2851dfc%40googlegroups.com.
Christopher Keele
Aug 4, 2019, 12:28:41 AM8/4/19
to elixir-lang-core
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.
Bruce Tate
Aug 4, 2019, 5:43:34 PM8/4/19
to elixir-l...@googlegroups.com
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
--
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 elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/edec2a8b-24b6-4750-9928-688315856e54%40googlegroups.com.
Reply all
Reply to author
Forward
0 new messages