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

[Jonathan Nieder <jrnieder@gmail.com>]

Hi Felipe,

Felipe Contreras wrote:

> I disagree. I think it's awfully useful to have color.ui = auto
> configured before reading the multitude of 'git branch', 'git show',
> and 'git diff' commands that are presented on first two sections. So
> useful, in fact, that I think it should be enabled by default.

This is why I think you had a good idea here.  When a program doesn’t
behave as I would like, it can be very comforting to know where its
dotfile is and be able to edit it (I’m not sure how I learn this for
most programs).  And it is much easier to parse git output without
reading it all when color is turned on, so that is a setting I imagine
could be useful to people.

On the other hand, it is far more pleasant to use a program that
doesn’t need configuration at all.  And as I mentioned before, it is
best to avoid wasted time at the beginning of the manual.

> 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_?

> 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.

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.

> However, I haven't met any proficient git user that got to that point
> by reading the user manual, so I think it must be completely
> re-thought.

I have met one.  (Well, he read the git tutorial and learned by using
git, too.)  I think the user manual’s pretty well written, though it
certainly has its gaps and rough spots.

> 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...

Thank you for working on this.  I hope you succeed in improving git’s
usability, one way or another.

Regards,
Jonathan