Re: [PATCH] Document patch syntax.

Karl Hasselström [off-list ref] writes:

On 2007-05-12 16:38:27 +0200, Yann Dirson wrote:

quoted

However, that makes me think we should probably use guideline for
the docs - here comes the question of which convention to use when
refering to the user. Do we address her directly ("you"), indirectly
("the user", "her" - don't remember where the "female user" use
comes from, but we could maybe follow this), even more indirectly
("one"), or any other way ?

I'd go with "you", or possibly "one" (but I strongly prefer "you").
Talking about the user in the third person ("the user", "her", etc.)
seems actively wrong when we are instructing the user on how to do
things.

With the context in question, I find 'the user' is the most
natural and neutral.

I think the "female user" use is not so widely accepted.  I
always found it to be a sign that the author, a lonely male nerd
developer, is wishing to live in a dream world where he becomes
a hero by helping an attractive female user that he would never
have chance to interact with otherwise in his real life ;-).

For tutorial/walkthru type of documentation, my usual preference
is "we", not "you".  "Now our little repository should be in
this shape."  "Let's change our Makefile to do a bit more."
That sets the tone that a slightly more knowledgeable friend is
helping the user by working together with him, instead of an
expert talking to a stupid user from a high place, but that is a
bit offtopic.

On Sat, May 12, 2007 at 12:02:24PM -0700, Junio C Hamano wrote:

For tutorial/walkthru type of documentation, my usual preference
is "we", not "you".  "Now our little repository should be in
this shape."  "Let's change our Makefile to do a bit more."
That sets the tone that a slightly more knowledgeable friend is
helping the user by working together with him, instead of an
expert talking to a stupid user from a high place, but that is a
bit offtopic.

I like that, too, but I don't think "we're" following it very well. Try
grepping through git/Documentation.

-Peff