I do appreciate the literary history (and I really do), but it's needlessly ambiguous in an environment where it can easily be construed to mean what it commonly and currently not in Shakespeare's time means: a plethora of writers, not a single writer.
Better to write documentation as you might write code:
Be conservative in what you do, be liberal in what you accept from others
it's needlessly ambiguous in an environment where it can easily be construed to mean what it commonly and currently not in Shakespeare's time means
It's not ambiguous. When used with a plural it means a plural ("the users, they did this"); when used with a singular it means a singular ("the user, they did that").
Nor has it changed since Shakespeare's time. It had exactly the same dual use back then.
How about adopting "she" as the generic pronoun, then? No chance of confusing it with a plural pronoun, and it's not subject to the gender-based critiques that "he" would be.
I think that's fine. There is nothing gender-specific in the antecedent "the user" so either "he" or "she" can be used in reference (though don't switch back and forth, I've actually seen writers try this and it gets really confusing).
The fact that it's confusing should clue you in to the fact that needlessly gender-specific pronouns are treacherous: you're not even actively aware of the gender assignment you make at the first pronoun, but are instantly aware when the assignment is violated.
So my argument for her or him, he or she, rather than they, is that her or him, he or she, in documentation humanizes the documentation. It piques my interest. There is an active person here.
It's not boring, dead trees, produced for some deadline documentation, Sally is doing something with this code! Bob needs to stop sending data!
He or she are far better to see in code comments for the same reason it's fun to encounter latin, or star trek quotes, or even curses.
They doesn't have that effect on me. They tells me the documentation was done grudgingly, likely by a prig. It is likely formally correct and will still say nothing, or be completely obtuse and thick.
If you want to humanize the documentation, introduce actual characters. "Here's Bob. Bob wants to update his widgets." Don't pretend that stereo instructions can be made to read like Elmore Leonard stories simply by changing pronouns.
At the point where you start synthesizing vibrant life stories out of gendered pronouns with "the user" as antecedent, you might consider instead just conceding the argument.
Comments
Once again, the gender-neutral singular "they" isn't inaccurate; it's been used by everyone from Shakespeare to CS Lewis.
I do appreciate the literary history (and I really do), but it's needlessly ambiguous in an environment where it can easily be construed to mean what it commonly and currently not in Shakespeare's time means: a plethora of writers, not a single writer.
Better to write documentation as you might write code:
Be conservative in what you do, be liberal in what you accept from others
In neither commit was the grammar remotely ambiguous; in both cases, the antecedent was clearly singular; "the user... they".
"They" is correct here, and always has been. "He" is arguably less correct, since the antecedent wasn't gendered.
it's needlessly ambiguous in an environment where it can easily be construed to mean what it commonly and currently not in Shakespeare's time means
It's not ambiguous. When used with a plural it means a plural ("the users, they did this"); when used with a singular it means a singular ("the user, they did that").
Nor has it changed since Shakespeare's time. It had exactly the same dual use back then.
How about adopting "she" as the generic pronoun, then? No chance of confusing it with a plural pronoun, and it's not subject to the gender-based critiques that "he" would be.
I think that's fine. There is nothing gender-specific in the antecedent "the user" so either "he" or "she" can be used in reference (though don't switch back and forth, I've actually seen writers try this and it gets really confusing).
The fact that it's confusing should clue you in to the fact that needlessly gender-specific pronouns are treacherous: you're not even actively aware of the gender assignment you make at the first pronoun, but are instantly aware when the assignment is violated.
So my argument for her or him, he or she, rather than they, is that her or him, he or she, in documentation humanizes the documentation. It piques my interest. There is an active person here.
It's not boring, dead trees, produced for some deadline documentation, Sally is doing something with this code! Bob needs to stop sending data!
He or she are far better to see in code comments for the same reason it's fun to encounter latin, or star trek quotes, or even curses.
They doesn't have that effect on me. They tells me the documentation was done grudgingly, likely by a prig. It is likely formally correct and will still say nothing, or be completely obtuse and thick.
If you want to humanize the documentation, introduce actual characters. "Here's Bob. Bob wants to update his widgets." Don't pretend that stereo instructions can be made to read like Elmore Leonard stories simply by changing pronouns.
At the point where you start synthesizing vibrant life stories out of gendered pronouns with "the user" as antecedent, you might consider instead just conceding the argument.