Repository navigation
api: harmonize personal pronouns #87
Description
Activity
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.
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.
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.
On Mar 7, 2016, at 3:03 PM, Robert Lindstädt notifications@github.com wrote:
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.
—
Reply to this email directly or view it on GitHub.Good hint. Shall we have this as "good first contribution" issue in the main repo?
Reacted by Steve MaoI'm happy to take a crack at this. Before I do, is this still something that needs to be done?
Reacted by Benjamin GruenbaumClosing 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.
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.