doc: relax prohibition on personal pronouns

[Trott]

Our personal pronoun prohibition is contrary to most current technical
documentation style guides. The prohibition on personal pronouns comes
from academic style guides. It results in an unnecessary formal tone. It
encourages wordiness and the overuse of passive voice.

This change to our style guide more closely aligns us with the style
guides of companies like Google, IBM, and Microsoft.

Google's style guide suggests avoiding first-person pronouns and
suggests: "Use the second-person pronoun (you) whenever possible."
Refs: https://developers.google.com/style/pronouns#personal-pronouns

IBM's style guide also recommends second-person voice ("Use second
person ('you')").
Refs: https://www.ibm.com/developerworks/library/styleguidelines/index.html

Similarly, Microsoft's style guide recommends using first person
sparingly and avoiding first-person plural. "In general, use second
person".
Refs: https://docs.microsoft.com/en-us/style-guide/grammar/person#in-general-use-second-person

Checklist

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

[bnoordhuis]

Hearty +1! If I need my shot of passive voice, I'll go read scientific papers.

[jasnell]

I'm going to have to maintain my (long standing) objection unless we can work out a strategy to improve the docs overall. Currently, the structure of our documentation is horrendous. There is exceedingly little consistency, some things are over-documented, other things are not documented at all. It's extremely difficult to find what we're looking for and the piecemeal way in which docs get edited without any real strategy or consistency means that they read in a very incoherent way.

That said, guides are separate from API reference, and I have no problem at all with more colloquial language in guide text. If we were to systematically begin to separate guide text from API reference text in the documentation, then I would have no problem with "you" in the guide sections.

[Trott]

That said, guides are separate from API reference, and I have no problem at all with more colloquial language in guide text. If we were to systematically begin to separate guide text from API reference text in the documentation, then I would have no problem with "you" in the guide sections.

We don't have guides in this repository. The things in the guides directory are not guides for end users. They are internal docs.

[Trott]

I'm going to have to maintain my (long standing) objection unless we can work out a strategy to improve the docs overall. Currently, the structure of our documentation is horrendous. There is exceedingly little consistency, some things are over-documented, other things are not documented at all. It's extremely difficult to find what we're looking for and the piecemeal way in which docs get edited without any real strategy or consistency means that they read in a very incoherent way.

Honestly, it seems like this is blocking a definite improvement over unrelated issues.

[Trott]

Currently, the structure of our documentation is horrendous. There is exceedingly little consistency, some things are over-documented, other things are not documented at all. It's extremely difficult to find what we're looking for and the piecemeal way in which docs get edited without any real strategy or consistency means that they read in a very incoherent way.

I share your frustration on this, by the way. However, I'll also add that these same criticisms could be applied to our tests, our code, and nearly everything else. It is all inconsistently structured. Many things get too much attention, and many things get not nearly enough attention. And so on and so forth. I think blocking this change discourages people from taking on the much larger, more difficult, and more-likely-to-be-contentious-and-stall task of solving those bigger issues.

[gireeshpunathil]

IIRC, we spent a lot of effort to remove pronouns to bring the doc where we are? Was there any report / concerns from users around the current (conservative) usage of pronouns? or else, I would maintain the status-quo.

[Trott]

IIRC, we spent a lot of effort to remove pronouns to bring the doc where we are?

Yes, some have definitely put in effort there. I don't think the effort spent on that should be a consideration, though. The question is whether it improves the documentation or not.

Was there any report / concerns from users around the current (conservative) usage of pronouns?

I am unaware of any complaints specifically about our current pronoun prohibition. I don't think users are likely to complain about such a thing, and are more likely to have complaints about the documentation being harder to read than necessary, for example.

[gireeshpunathil]

ok, given there are no reported issues, and given the statement that users are unlikely to report issues on this, I would hold that the premise in which we prohibited pronouns in the first place hasn't changed, and I am -1 on this change.

[jasnell]

We don't have guides in this repository. The things in the guides directory are not guides for end users. They are internal docs.

Sure we do, we just don't call them as such. Consider the N-API docs in contrast to say, the fs API reference. The former is most definitely a guide in comparison. Another example of guide vs reference can be seen the two primary sections of the Buffer docs and here

And no, I'm not blocking for irrelevant reasons. Allowing the use of 'you' in the docs is not going to improve them, even incrementally, if there aren't more substantial changes to structure. It'll just be churn with little noticeable gain in quality.

[Trott]

given there are no reported issues, and given the statement that users are unlikely to report issues on this,

I don't expect it to affect your -1 on this, but just to make sure I'm not misunderstood: What I meant by the statement was that users are more likely to report issues that are caused by the pronoun avoidance than to complain about the pronoun avoidance itself. (And that should be a reason to reconsider pronoun avoidance.)

Readers of the documentation are unlikely to be aware of the pronoun avoidance guideline. However, they are likely to be aware of issues that result from pronoun avoidance, like convoluted sentence structure and an over-reliance on passive voice.

[gireeshpunathil]

@Trott : I got it - it is not the issue with the presence of the pronoun, but the readability that the users are likely to be concerned. I am willing to change my mind, if I see evidence of that pattern from the end-users

[Trott]

Sure we do, we just don't call them as such. Consider the N-API docs in contrast to say, the fs API reference. The former is most definitely a guide in comparison. Another example of guide vs reference can be seen the two primary sections of the Buffer docs and here

That's a valid point. And, as you note, a lot of our docs switch between the two. Which seems to imply that you'd be OK with second-person pronouns in some places in some docs, but not in other places in those same docs. (Which I'm not criticizing--it's a reasonable position to have.)

[bnoordhuis]

@gireeshpunathil A rule of thumb I've learned is that no more than 10% of prose should be in passive voice, otherwise it gets hard to follow for many people, native and non-native speakers alike. Our docs certainly go over that threshold in many places.

[Trott]

In addition to the style guides already mentioned (Google, Microsoft, IBM), I took a look at Linux man pages and at MDN. They both use second-person pronouns freely. (They both have style guides that default to Chicago Manual of Style.)

Browsing MDN and Linux man pages show lots of uses of you, your, and so on.

The Linux man page for the find command uses you and variants 67 times, not counting boilerplate uses.

The Linux man page for the man command use you and variants 27 times, not including 4 occurrences that are in boilerplate footer text.

MDN page for String has 9 occurrences of you and variants. For example:

This last form specifies a template literal: with this form you can interpolate expressions.

MDN page for this:

You can always easily get the global object using the global globalThis property, regardless of the current context in which your code is running.
…
You can still prepend arguments to the call….

And so on.

Linux man page style guide:

For details not covered below, the Chicago Manual of Style is usually a good source; try also grepping for preexisting usage in the project source tree.

MDN writing style guide:

If you have questions about usage and style not covered here, we recommend referring to the Microsoft Writing Style Guide or, failing that, the Chicago Manual of Style.

Chicago Manual of Style Online:

The second person is useful in technical writing….

[Trott]

Allowing the use of 'you' in the docs is not going to improve them, even incrementally

It certainly won't improve the overall structural problems. However, it will encourage individual sentences to be written in a clear and direct fashion. It will remove the current encouragement to over-use passive voice, which is a real problem in our current docs.

It'll just be churn with little noticeable gain in quality.

Why do you say it will be churn? I don't think anybody is going to go through and start adding second-person pronouns willy-nilly just because they can. What this will do, though, is encourage clear writing, at least for individual sentences and maybe paragraphs. It will also avoid unhelpful nits about usage of you on contributions from new folks.

Lastly, it will signal to technical writers that we're not going to fight change to preserve an unhelpful prohibition.

(I was on Team No Personal Pronouns in the past. Try letting go of it. The docs will be fine. Honest!)

[gireeshpunathil]

The Linux man page for the find command uses you and variants 67 times, not counting boilerplate uses.

:) this may not be a head-to-head analogy, but for a similar circumstances, you held in the past that:

Someone in a different context, a different project, and different language found something a little bit similar to this to be useful. That is not an argument for doing it everywhere.

#32118 (comment)

@gireeshpunathil A rule of thumb I've learned is that no more than 10% of prose should be in passive voice, otherwise it gets hard to follow for many people, native and non-native speakers alike. Our docs certainly go over that threshold in many places.

my point is: what has changed since the time we explicitly removed pronouns? I am yet to see an end-user complaining that doc is less readable because of passive voices.

[Trott]

this may not be a head-to-head analogy, but for a similar circumstances, you held in the past that:

Someone in a different context, a different project, and different language found something a little bit similar to this to be useful. That is not an argument for doing it everywhere.

I agree that "Everyone else is doing it", by itself, is not a good reason to adopt a practice. I'm saying: We're doing something unusual, so we should reflect on whether we have a good reason to do it (we don't) and whether it has any downsides (it does).

[jasnell]

@Trott, as a path forward, let's start working towards a more comprehensive plan on the docs, of which this can be a component... starting with, rather than continuing to modify and maintain our own doc style guide, let's adopt one of these referenced ones. I mean, there are always going to be an handful of rules that are specific to this project (using markdown with 80-char line breaks for instance, and the mechanics of how API reference details like arguments and return values are to be presented), but when it comes to details on the guide elements, we can replace a significant chunk of the existing doc style guide with a reference to the much more comprehensive google style guide (for instance).

[Trott]

@Trott, as a path forward, let's start working towards a more comprehensive plan on the docs, of which this can be a component... starting with, rather than continuing to modify and maintain our own doc style guide, let's adopt one of these referenced ones. I mean, there are always going to be an handful of rules that are specific to this project (using markdown with 80-char line breaks for instance, and the mechanics of how API reference details like arguments and return values are to be presented), but when it comes to details on the guide elements, we can replace a significant chunk of the existing doc style guide with a reference to the much more comprehensive google style guide (for instance).

I've been wanting to/planning to propose adopting Microsoft's style guide with Chicago Manual of Style for things not covered by Microsoft, but I wanted to dig a bit deeper before proposing it. There are trade-offs. (Biggest problem with Chicago Manual of Style is that it's not available freely online.) However, if it helps to reveal that as my current plan/aspiration, that's my current thinking.

That would basically mirror what MDN does:

• Here are a handful of rules specific to us.
• For everything else, look at Microsoft's style guide.
• If it's not covered in Microsoft's style guide, refer to the most recent edition of The Chicago Manual of Style.

[mhdawson]

I'm +1 to using an existing well used style guide versus maintaining our own custom one. Seems like that would help us leverage best practice and what others have found works.

[Trott]

I'm +1 to using an existing well used style guide versus maintaining our own custom one. Seems like that would help us leverage best practice and what others have found works.

I appreciate that you're trying to be constructive and positive. Are you +1 on blocking this PR pending the adoption of said style guide? If not, can you approve this PR?

Everyone (including me) is in favor of adopting an extant style. Literally, I cannot realistically imagine anyone being opposed to it. The disagreement is about whether it makes sense to hold up this change pending that.

[mhdawson]

@Trott, @jasnell has a blocking objection on the PR and I'd kind of agree that we should choose that style versus tweaking what we have, updating etc. However I don't feel strongly enough to block.

[Trott]

@Trott, @jasnell has a blocking objection on the PR and I'd kind of agree that we should choose that style versus tweaking what we have, updating etc. However I don't feel strongly enough to block.

I'm happy to report that we've adopted the Microsoft Style Guide as of bc8a4df.

@jasnell What else (if anything) needs to happen to satisfy your concerns?

[jasnell]

I'd still like to see us make a number of other important improvements but you can clear my objection here

[Trott]

I'd still like to see us make a number of other important improvements but you can clear my objection here

I'm interested to hear what they are, even a non-exhaustive list, but happy to have that conversation privately if you'd prefer. (And, of course, if you'd prefer not to have it at all, I'll certainly respect that.)

The thing I want to do next is find all the things that are in both our style guide doc and in the Microsoft style guide, and either remove them from ours or get it super short with a link to the relevant stuff in the Microsoft guide.

dismissed per comment

[Trott]

@gireeshpunathil Are you still -1 on this? If so, can you use Request Changes? If not, then this is ready to land.

[Trott]

Rebased to resolve merge conflict.

[Trott]

@gireeshpunathil Are you still -1 on this? If so, can you use Request Changes? If not, then this is ready to land.

Re-ping @gireeshpunathil to get a red X Request Changes on this or confirmation that it's not blocked. I don't want to land this over your or anyone else's objection, but I also want to land it if there's no blocking concerns.

[gireeshpunathil]

no blocker from my side.

[Trott]

Landed in 448834c