Re: [PATCH v2 0/2] user-manual: new "getting started" section

[Felipe Contreras <felipe.contreras@gmail.com>]

On Sun, Oct 25, 2009 at 1:14 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Felipe Contreras wrote:
>> Supposing that color.ui is 'auto' by default,
>
> Should it be?  I think it would not be too hard to detect a color
> terminal by checking $TERM.  Are many people bothered by color?  Do we
> need some way to make it more obvious how to turn color _off_?

I think it should be.

>> No, but "improving" needs "changing", and the discussion I see is
>> biased towards "not changing".
> [...]
>> I don't think the user manual is achieving that purpose. I don't know
>> if it's the user manual's fault, or git's UI. Both areas need a lot of
>> improvement (as the git user survey suggests), and I've tried to
>> improve both with a lot resistance in both. So I'm not very hopeful
>> anymore.
>
> I hope you have not misunderstood.  I cannot speak for everyone else
> here, but I know I am happier when (1) fixes match problems to be
> solved in a documented way and (2) fixes do not unnecessarily break
> unrelated habits.  One way to bring this about is to justify each
> change by explaining what real problem it will solve and how it avoids
> collateral damage.  Without that justification, a change is indeed
> dangerous and might be worth resisting until it gets clarified.  But
> this is not meant to prevent fixes from occuring at all.

Well. I've sent many patches, and gone through several iterations.
After fixing all outstanding issues, addressing all the comments, and
getting several "I like this" votes, Junio suddenly decides he doesn't
like the initial changes at all and doesn't provide any way forward.

I don't see how that's an environment that fosters changes.

> Could you list some UI patches that were overlooked or not properly
> addressed?  Maybe people just forgot about them or were waiting for an
> updated version, or maybe the problems some solve weren’t articulated
> clearly yet.  I would be glad to help out in any way I can.

For example there have been many attempts to bring the 'git stage' to
foreground of the UI; right now it's kind of hidden and many people
don't even realize it's there. Even simplistic attempts as
standardizing --index, --cache and so on into --stage have failed
miserably.

Again, there doesn't seem to be a path forward. Perhaps the git's
stage will remain an obscure feature of git forever. (all the input
from git user's survey points out that people are not really using it)

>> Judging from the luck I've had pushing even the simplest
>> changes I don't think it will improve much more, unfortunately.
>
> Even the simplest changes can be hard.  But I hope they do not amount
> to nothing.  I hope at the very least the git-config manual page will
> improve...

What I mean is: if the simplest changes are *impossible*, then there's
barely any hope of progress.

Cheers.

-- 
Felipe Contreras