Re: [PATCH] Document patch syntax.

From: Junio C Hamano <junkio@cox.net>
Date: May 12, 2007, 19:02 UTC
Message-ID: <7vodkpzwzj.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <20070512183255.GD28039@diana.vm.bytemark.co.uk>

Karl Hasselström <kha@treskal.com> writes:

Show 13 quoted lines

> On 2007-05-12 16:38:27 +0200, Yann Dirson wrote:
>
>> 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.