This repository was archived by the owner on Mar 25, 2018. It is now read-only.
Repository navigation
This repository was archived by the owner on Mar 25, 2018. It is now read-only.
api: harmonize personal pronouns #87
Description
The use of personal pronouns seems a little inconsistent. The WG could decide on whether or which ones to use and harmonize those. Any english native speakers could give a hint here, maybe there are sites (like wikipedia), who have standardized the use of those.
Activity
svozza commentedon Mar 13, 2016
I think consistency is key. As someone new to contributing doc fixes, I found it confusing that in two separate places the use of personal pronouns are discouraged yet the API references are littered with them.
The problem with making a decision like this is that its very subjective, the admonishment to avoid personal pronouns in formal documentation is a bit of an anachronism now. If you look at the .NET or AWS reference documents they favour 'you` and the active voice, whereas Java follows the more traditional path. Personally, I prefer the more formal style for API documentation but definitely not guides as they would feel stuffy and stilted if written in that manner.
It might be worth reading some other the style guides, e.g., OpenStack, MDN or Apple for inspiration - interestingly, they all recommend using 'you'. Unfortunately, many guides from the big companies, such as MS or IBM, aren't free.
benjamingr commentedon Mar 13, 2016
I think that as long as we avoid pronouns terms that exclude people it's fine to use them inconsistently - it has never bothered me before.
chrisdickinson commentedon Mar 13, 2016
The use of pronouns is covered in the style guide in this repo (https://github.com/nodejs/docs/blob/master/STYLE-GUIDE.md). Nonconforming reference docs should be updated to reflect the style guide as issues come up.
eljefedelrodeodeljefe commentedon Mar 13, 2016
Good hint. Shall we have this as "good first contribution" issue in the main repo?
snollygolly commentedon Oct 19, 2016
I'm happy to take a crack at this. Before I do, is this still something that needs to be done?
Trott commentedon Mar 13, 2018
Closing as this repository is dormant and likely to be archived soon. If this is still an issue, feel free to open it as an issue on the main node repository.