Remove passive voice

[dtolnay]

I'm not satisfied with the passive voice convention that has developed for example descriptions. I find it backwards and harder to read than I would like.

Without meaning to pick on any individual instance, let me use this one as an example:

HTTP POST request to gists API v3 is made with reqwest::Client in order to create a gist. A request body is created with serde_json::json! macro and set set with RequestBuilder::json. Request is prepared with Client::post, authenticated with RequestBuilder::basic_auth and synchronously executed with RequestBuilder::send.

Gist is subsequently deleted with HTTP DELETE request prepared with Client::delete and executed as before.

I don't have a strong preference between "make" and "makes" but either way I think this would be more readable without passive voice "is made." The rustdoc convention is "makes" tense so here is what that would look like:

Makes a POST request to GitHub's gist API to create a new gist. Then makes a DELETE request to delete the gist with the id that was just created.

The reqwest::Client is responsible for setting up details of both requests including the endpoint URL, the authentication, and the request body. Here the POST body comes from serde_json's json! macro which provides a way to pass an arbitrary JSON body, but elsewhere a struct may be more convenient (link to Serialize example). The DELETE request requires no body.

The call to RequestBuilder::send synchronously executes the HTTP request and returns the GitHub server's response.

Any opinion @budziq? I know you were an advocate of the passive voice.

[budziq]

Hmm I guess that my passive voice examples are relatively hard to grokk in comparison to your rewording 😞.
I did not see a consistent convention at the time so I have started to enforce (admittedly sub-optimal) one. So big 👍

ATM I only see a big problem with description consistency as we do not have guidelines here.

I would suggest renaming this issue to "make the description consistent" with at least following action items:

• provide a guideline or a stellar example with metainformation regarding the language and wording requirements in CONTRIBUTING.md
• remove the passive voice ;P
• find a list of non normative examples and fix them one by one in a tracking issue

[dtolnay]

We're all clear on #106 so @budziq would you be interested in taking a pass at improving these? I'll work on contributing.md with an example.

[budziq]

I'll cleanup the passive voice from my examples. But it is a large (and less than exciting) effort so I would rather wait for clear guideline I can imitate (I'm not not native english speaker so my perspective regarding the language is largely skewed as evident from this issue :) ).

[budziq]

Well this is not disheartening at all 😞

Passive voice examples by budziq:

• Generate random numbers within a range
• Generate random numbers with normal distribution
• Generate random values of a custom type
• Encode a string as application/x-www-form-urlencoded
• Remove fragment identifiers and query pairs from a URL
• Make a HTTP GET request
• Download a file to a temporary directory
• Query the GitHub API
• Create and delete Gist with GitHub API
• Enable log levels per module
• Log to the Unix syslog

Passive voice examples by other contributors:

• Run an External Command and Process Stdout
• Encode and decode base64
• Log messages with a custom logger
• Log messages to a custom location

[brson]

Aw, don't feel bad @budziq! Look at all those great examples.

[dtolnay]

Reopening until I get a chance to write about this in contributing.md.

[tyoc213]

Well, english is not my natal language... so a reference, pdf book (free of course) or something related to what is pasive voice and how to redact properly would be great! (ie, for me the passive voice and the not passive voice in the OP are OK to me, because I dont get what "this mean", I only read and "get it").

Found this http://www.sjsu.edu/writingcenter/docs/handouts/Passive_Voice.pdf thought I still dont get it much.

[dtolnay]

@tyoc213 The point is that as you read a sentence, you should be able to understand the fraction of the sentence you have read so far. When you are 25% of the way through the sentence, you should understand what that 25% means and how it contributes to the full sentence. When you are 50% of the way through the sentence, you should understand what that 50% means, etc.

In passive voice, often things are backward so that you read the first 50% of the sentence, misunderstand it or don't understand it, read the rest of the sentence, and last 50% gives you the context to understand the first 50%. This is subconsciously frustrating and makes the material seem more confusing than it is.

Using an example from your pdf link:

Passive: The student was recommended by Sally to attend the workshop.
Active: Sally recommended that the student attend the workshop.

As you are reading the passive voice:

"The student was recommended"—I have no idea what this means.
"The student was recommended by Sally"—Maybe Sally wrote a letter of recommendation saying that her company should hire this student. (This turns out to be the wrong interpretation of this part of the sentence, but you don't find out until later.)

Versus active voice:

"Sally recommended"—Already I understand what this sentence is about.
"Sally recommended that the student attend"—Continues to make perfect sense so far.

Maybe the difference is more subtle to a non-native English speaker because you could be accustomed to reading sentences more than once to fully understand them. In that case it wouldn't affect you if the sentence needs information from the second half to understand the first half correctly.

[tyoc213]

Well probably but Im a pro at reading english xD.. it seems that it is more difficult to people that droped out of school http://www.quickanddirtytips.com/education/grammar/active-voice-versus-passive-voice?page=1 and as I have read spanish also has pasive and active, so... but I normally dont write much and less to be read by other people, I guess I normally write in pasive form.

[budziq]

it seems that it is more difficult to people that droped out of school

@tyoc213 please note that the rust-cookbook is aimed to be an introductory resource for programmers of different lingual and academic backgrounds. So we try to keep the prose short and as simple or simpler than the actual code examples.

[budziq]

Maybe the difference is more subtle to a non-native English speaker because you could be accustomed to reading sentences more than once to fully understand them.

It might be so, but on the other end of the spectrum formal English education tends to ingrain more complicated forms in non native English speekers (like myself).