doc: remove personal pronoun guidance from style guide

[Trott]

In order to facilitate a more formal voice, the style guide recommends
avoiding personal pronouns. In practice, this results in lots of nits
for our docs without actually improving them. There are lots of ways our
docs can be improved. Making them more formal seems low value,
especially for all the PR comments this guidance generates.

So, remove that guidance from the style guide.

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[Trott]

@nodejs/documentation @gibfahn

[Trott]

(Also: First time submitting a PR without having to list the subsystems at the bottom. A+! Will submit PRs again!)

[Trott]

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite/231/

[jasnell]

I am firmly -1 on removing the restriction against using you, your, I, and we.

[Trott]

I am firmly -1 on removing the restriction against using you, your, I, and we.

@jasnell Could you please provide a brief explanation why?

[jasnell]

Because I have a preference for the more formal voice in API documentation. The less formal voice is just fine for guides and tutorials. It adds nothing of value to API docs.

[gibfahn]

Cross-posting from #18699 (comment)

Why? I've never really understood this.

If you pick a random page from the std library of another language, they all seem to use "you" indiscriminately:

• Rust
• Python
• Ruby
• Go
• JS (MDN)

Fundamentally we're instructing users of Node in how we think they should use the APIs we provide. Making the tone more formal (e.g. making everything passive) doesn't really change that.

[jasnell]

If I'm in the minority in my opinion, then so be it.

[cjihrig]

I agree with @jasnell here.

[Qard]

I somewhat agree with @jasnell in that the informality that can result from acceptance of personal pronouns can lead to more verbose documentation that is harder to follow.

I'm +-0 on this, but I think it'd be good if we could gather a little more community input on this.

[gibfahn]

I'm a bit on the fence, I think sometimes avoiding you makes sense, but other times, like in https://nodejs.org/api/synopsis.html, we're still addressing the whole thing to the user, just carefully avoiding the word you. In @Trott 's original suggestion (#17977 (comment)) I'm not sure that actually improved the docs.

As another example here:

In general, check for the accessibility of a file only if the file will not be used directly, for example when its accessibility is a signal from another process.

does adding a you should instead of the first comma make the docs worse? I think it makes them clearer.

So I guess IMHO sometimes (often?) avoiding you is good, it makes you reword the documentation so it describes the API rather than being a dialogue with the developer. But sometimes you are talking directly to the developer in the API docs, at which point avoiding it just means obfuscating that fact.

@nodejs/collaborators , please weigh in!

Also worth noting that only one of this and #19030 should land 😁

[Qard]

That's fair. I think rather than fully removing the text banning personal pronouns it might make sense to just reword it to suggest avoiding them and specifically avoiding conversation-style writing.

[Trott]

reword it to suggest avoiding

@Qard That's how it's written already. It says "Generally avoid" rather than "Do not use" or something like that. So if that's what the consensus is (or if consensus can't be reached), then yeah, that's the way it's gonna be. :-D

[Qard]

Ah, yeah. Missed that. 😅

[vkurchatkin]

How about we remove "cats" while we are here? I know, it is supposed to be funny, but it doesn't seem appropriate.

[tniessen]

No strong opinion here, but I think I am in favor of keeping it a bit more formal.

In general, check for the accessibility of a file only if the file will not be used directly, for example when its accessibility is a signal from another process.

does adding a you should instead of the first comma make the docs worse? I think it makes them clearer.

This could be users should or developers should as well, or even It is recommended to check the accessibility.... My point is that it should be possible to keep our docs formal without making them less clear.

[Qard]

A valid counter-argument being that demanding formal writing style may discourage docs contributions from people who speak English as a second language and may not be as familiar with formal writing styles as a native speaker.

[mcollina]

I'm -1 on this one. A formal voice reads better in docs.
However, I can see why we want this change.

[mcollina]

I would replace Generally with Try to. It should not prevent something from landing, but it would be best fixed.

[thefourtheye]

Google's style guide recommends to use "you" whenever possible.

I personally prefer formal text. Although @Qard's point seems very valid to me. So, -0.

[hashseed]

"cats" seem out of place. Imagine a developer who does not speak English as first language (and even those who do). They would be very confused if documentation for some reason refers to "cats".

[bnoordhuis]

the informality that can result from acceptance of personal pronouns can lead to more verbose documentation that is harder to follow

Fair point, but that's also true of too much passive voice.

I would argue that the docs should be optimized for non-native speakers first, native speakers second. Pick what is simplest and concisest; the fewer vowels, the better.

[Trott]

I'm surprised at suggestions that the formal voice results in more easy-to-understand documentation. I'm unaware of any evidence for this. I think the benefit of formal voice is more professional-sounding documentation. But more understandable? I'm skeptical.

Taking the first instance I could find in https://nodejs.org/api/documentation.html, compare:

If errors are found in this documentation, please submit an issue or see the contributing guide for directions on how to submit a patch.

If you find an error in this documentation, please submit an issue or see the contributing guide for directions on how to submit a patch.

The second one is clearer, because the "please submit an issue..." stuff is what someone should do if they find an error, and that's clear at the outset of the sentence. By starting with "If errors are found in this documentation...", the meaning could at first be interpreted as "If the project finds an error in this documentation..." causing the reader to expect the sentence to be something more like "If errors are found in the documentation, corrections will be publish in an errata document available at...." or something like that.

We could try to avoid that ambiguity in formal voice, but it doesn't result in an easier-to-understand formulation:

If a user finds an error in this documentation, that user may submit an issue or consult the contributing guide for directions on how to submit a patch.

Is that really better than this?:

If you find an error in this documentation, please submit an issue or see the contributing guide for directions on how to submit a patch.

(Spoiler alert: No, it is not.)