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

[Michael J Gruber <git@drmicha.warpmail.net>]

Felipe Contreras venit, vidit, dixit 12.11.2009 00:15:
> 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.

Back then (before my involvement with git) the result of the discussion
was something like: "Since some of us are way more opposed to the use of
colors than others are in favor..." This does not sound overly democratic.

Feel free to bring this issue on for a change in Git 1.7.0. It would be
good to research any possible incompatibilities this would imply (other
than the looks of the output),

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

The process can be frustrating at times. Many patches go through many
rounds. I've had occasions where I got frustrated and gave up, as well
as those where I learned a lot and the actual result was much better
than it would have been without thorough discussions. It's this process
which tries to ensure that the project is moving forward most of the
time, rather than sporadically back and forth; moving forward maybe a
bit slower, but still at an impressive overall rate.

Regarding this specific patch series: I took part in the initial
discussion, and got frustrated by the original poster's seemingly
unwillingness to accept advice, so I left. I'm not drawing any general
conclusions, and please don't take this as an ad hominem argument.
Sometimes it's simply a matter of mismatching participants.

It's just my impression that many people retreat from a discussion
because they feel it's getting unproductive (from their particular point
of view), maybe hoping the thread will die out sooner or later. Once it
looks as if something they object to could be included they come back
with counter arguments. This makes the discussion seemingly go back and
forth, but is a natural sociological effect.

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

I didn't read that out of the survey. On the other hand, the last survey
pretty impressively showed where it had been publicized most
prominently. One should keep that in mind when interpreting the results.

If you care to go back to that discussion you see that there is good
reason for having both --cached and --index. They are different. "git
help cli" explains this nicely.

"To stage" has been introduced to describe what "git add" does to people
who hard wire "add" to the meaning it has in other VCSes. In fact, this
would be unnecessary if the concept of Git as a *content* tracker could
be transmitted more successfully. Git cares about content only, so what
could "git add" possibly mean?

"git stage" is a failed follow up ui experiment.

In this regard, I think the problem is that there are really two kinds
of people in terms of learning style:

- Some prefer recipes, similarities with previously known recipes. "How
do I...?" And then try do understand "How does (G)it...?" from that.

- Some want to understand concepts first: "How does (G)it...?" And then
figure out how to use (G)it to do what they want.

I'd guess most developers and a large fraction of the "technical crowd"
belong in the second camp.

I still think we should both

- try and teach concepts early, emphasize that Git is different
(content, index, branch - that's it)
- make Git behave in "expected ways", making it easy for the (willing)
beginner) without compromising its usefulness as a power tool.

I better stop before I digress even more from the original topic :)

Michael