Hi, On Sun, Jul 26, 2020 at 07:54:17PM +0200, Tim Düsterhus wrote: > Jackie, > > Am 26.07.20 um 19:02 schrieb Jackie Tapia: > > Thanks for the suggestion, Tim. > > > > That commit message sounds good to me. > > > > Your patch looks good to me now. I've put Willy into Cc to perform the > final review and commit the patch.
Thanks Jackie, and thanks for handling this review, Tim. I've read it (and indeed it's much easier now that the first one) and overall it looks good to me as well. Just a small point, Jackie, as I noticed you fixed several bad constructs of "he" instead of "it", it's worth noting that in some latin languages (like French or Spanish), a number of common words are arbitrarily male or female. A car is female, a truck is male, a plane is male and a space shuttle is female. I could give plenty of examples like this, as there's almost no equivalent for "it". It gets funny when (ab)using some english words in our jobs because they automatically get the gender of their local equivalent. As you noticed, some of these slip from French to English when docs are written, beause while the exercise of translating what you think to another language is hard, the exercise of thinking in another one is even harder, and sometimes reading such things are even not noticed, they are hard-wired in one's brain. As such I think that adopting an advanced form of English that's not even taught in schools will be even harder to follow and understand for most of us non-native users (hence the efforts of "he/she" that you've noticed at a few places). This comforts my beliefs that avoiding mentions of the user in general is by far the best solution, and that when not possible (due to generalizing), it's best to use a plural form (since in this case what is described doesn't apply to a single user but to all of them). In this case instead of writing "upon error on any of the parallel requests sent by a user, he/she will be notified by an error message" (which admittedly looks ugly), or "upon error on any of the parallel requests sent by a user, they will be notified by an error message" (which is now wrong since it parses as the requests being notified instead of the user, at least to any of us for whom English was only taught as a second language), we'd rather write this using a repetitive form like "... the user will be notified", or an alternative one like "Users whose requests triggering an error will be notified by a response...". This avoids such advanced and difficult forms that are clearly not mastered by all those who almost only use english to write documentation. Overall, while I'm used to say that "I/you/we" should absolutely be avoided in docs (it's not the place to discuss with the user but to explain rules), we could probably mention that "I/you/he/she/we" are to be avoided and that the only pronouns left are "it" for singular and "they" for plural, implying that users will always be designated using the plural form. This simplifies everything and will force doc writers to think about simpler sentences that are less ambiguous, and more importantly that are understandable even by the many who don't have 10 years of English practice behind them. Regards, Willy
