Rule for enforcing use of passive voice

[DerekNonGeneric]

In professional documentation, I expect the passive voice. It’s not clear who the “we” would be here.

Originally posted by @GeoffreyBooth in nodejs/node#40708 (comment)

---

Strong agree with @GeoffreyBooth from me — perhaps we should consider including retext-passive in our preset to assist us in catching these.

[Trott]

I'm strongly opposed to this suggestion.

First of all, and least importantly, retext-passive does the opposite of what you are asking for here. It flags passive voice as a problem.

Second, the recommendation for active-voice "we recommend" over passive-voice "it is recommended" is from the Microsoft Style Guide. The reason we adopted the Microsoft Style Guide was to avoid this kind of style-guide second-guessing. Sure, we need to make sure people spell it Node.js and not NodeJS. That needs to be in our local style guide. But we do not need to work out within the group whether it's better to use serial commas or not, whether passive voice or active voice is preferred, whether "may" is preferable to "might" or the other way around, and so on.

The Microsoft Style Guide, in an effort to make documentation friendly/approachable/informal, recommends active voice for most content. Let's not second-guess them.

When the decision to use Microsoft's Style Guide was being made, the reason I proposed the Microsoft Style Guide was because that's what MDN uses, and MDN seemed to me to be the gold standard for online JavaScript documentation. We link to MDN all over the docs when we need to link to types and things like that.

I'm sorry if you find the style too informal or otherwise not what you would choose, but at the same time, please, let's not do this.

[Trott]

Oh, by the way, if you want to try to get your change in upstream, you can open an issue or a pull request at https://github.com/MicrosoftDocs/microsoft-style-guide. If you can make the case for a change or (more likely) an exception/clarification that would apply to the case that started this conversation, then those changes would naturally be adopted by Node.js over time.

[GeoffreyBooth]

I’m surprised to learn that the Microsoft style guide discourages the passive voice. I thought it was pretty standard that computers say things like “File not found” and not “I could not find the file” or “Windows could not find the file” or whatever. I thought the same extended to documentation.

Anyway this is why we follow a larger standard, to avoid debates like this. This isn’t a Node-specific thing, so if it’s a settled question then we shouldn’t make an exception for ourselves.

[Trott]

I thought it was pretty standard that computers say things like “File not found” and not “I could not find the file” or “Windows could not find the file” or whatever.

They explicitly call out error messages like that as a situation where passive voice is appropriate. See https://docs.microsoft.com/en-us/style-guide/grammar/verbs#active-and-passive-voice where the first bullet under uses for passive voice says that it is useful "especially in errors, warnings, or notifications".

[Trott]

I'm going to close this, but please feel free to re-open or comment if the issue is not in fact settled. Thanks!