Avoid addressing the user directly when writing docs?

To the Documentation Workgroup: Should we avoid addressing the user directly when writing docs? I believe this was up for discussion on python-dev last year, but I was unable to find it in the archives, so I guess my memory fails me. Also, I cannot find any recommendations regarding this in the devguide.

During reviews affecting the docs in some way, some core devs will request a “non-personal” tone. Here’s a recent example from GH-29200, quoting @ambv:

Outside of tutorials and howtos, we avoid addressing the reader as "you", instead using a style where the "you" is implied. Instead of saying:

> If you want X, do Y.

simply say:

> To achieve X, do Y.

Does the Documentation WG have an opinion regarding this, or is it just up the personal preference of the various code owners and maintainers?

Personally, I’m aligned with Łukasz’ opinion :slightly_smiling_face: :open_book:

cc. @steven.daprano (as per discussion on bpo)

cc. @Mariatta, @willingc, @julien, @nedbat (Documentation WG)

2 Likes

Both passive and active voice have their uses, but I don’t think the

argument here is actually about active versus passive voice. In the

example given:

If you want X, do Y.



To achieve X, do Y.

they are both in active voice. See the section on imperative verbs here:

Passive voice would be:

X is achieved by doing Y.

Yeah. The title is slightly misleading. I’ll see if I can reword it to clear things up a little bit.

UPDATED: @steven.daprano, is it clearer now?

This is my reference text on the matter: The second person is OK in developer documentation (but don’t take my word for it) | Daniel D. Beck

3 Likes

Thanks, Juan, that’s a very interesting read.

Yup, I had been meaning to weigh in here. I always learned the more “formal” writing, but there’s no doubt there’s been a trend to consider 2nd person more accessible and welcoming, and many projects now state that’s their writing style (I ran across it in the Bazel doc style guide just recently). Trends do change. That said, that also doesn’t mean the example from above:

> If you want X, do Y.

simply say:

> To achieve X, do Y.

is wrong… simpler is better, and if writing second-person causes you to need to be more wordy (I’ve had this happen to me), then just don’t do it. This one isn’t more wordy in second person, but it’s not as direct.

2 Likes

My take is:

  • Active should generally be preferred over passive.
  • Impersonal should generally be preferred over personal.
  • Affirmative should generally be preferred over negative.

BUT, to paraphrase George Orwell:

Break any of these rules sooner than say anything outright barbarous.

3 Likes

I was taught that using simpler, more direct language can be easier for non-native speakers (of whichever language) to understand. It depends on the kind of documentation and the audience, but even API and reference documentation may be written in a style that is more “active” than is traditionally expected.

For what it’s worth, “Python in a Nutshell” has many sentences using “you” (and not a few using “we”) and O’Reilly editors have never objected to that; I don’t see why other docs need to be more formal and stilted than O’Reilly books. (I’m not a native speaker of English, so one might think these uses in the first two editions where i was the sole author somewhat suspect; but now I have co-authors who ARE native speakers, from both England and the US, and all are fine with it).

2 Likes

My take on this comes from university courses on technical writing that I took. I also recall a conversation about this during one of the PyCon sprints a few years back but this was, forgive the pun, informal. Anyway, as demonstrated by industry-wide guidelines in Juan Luis’ post, English moved on from this formality.

Stylistically I still prefer the impersonal style as it’s easier to quote because you don’t have to worry about who the “you” in the quoted text refers to. I don’t feel very strongly about adding this to the Dev Guide as a recommendation though. It’s simply something I’ll continue using in my own writing. At the same time, I’ll stop pestering other contributors about this style in their pull requests. I believe that’s fair enough?

1 Like

There are certainly some cases where I would much rather have a writer use the second person than the third person, due to the limitations of the English language, in light of the new sensitivities to pronouns. I was taught way back in my school days to avoid the second person in formal writing, but I have grown out of that, over the years. If often makes sentences crisper. It can also forge a sense of a bond between writer and reader.

1 Like

Thanks for your input everyone! I’m still interested in the Documentation WG’s opinion, though :slight_smile:

My personal opinion would be to match the style of the writer in already created documentation (mostly to avoid unnecessary documentation churn).

In new documentation, I personally prefer the more direct approach for reference documentation (no “you”). While in a new tutorial, the more personal “you” may be more approachable.

1 Like