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

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

On Sun, Oct 25, 2009 at 6:08 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>>> I'm inclined to to discard the first patch.
>>
>> And you decided to mention that after many people including you, have
>> agreed that it's a good idea?
>
> This line of argument is wrong and counterproductive.  Of course, after
> reading what others said and thinking about it more myself, I can change
> my mind based on their opinions.  Otherwise there is no point in having
> any mailing list discussion.
>
> People propose changes, and two things can happen:
>
>  (1) I and others may think it is not a good idea, clarifying argument may
>     come from the original author and/or additional arguments defending
>     the change may come from others.  People who thought it was not a
>     good idea may change their mind, and the patch gets accepted.  git
>     becomes better.
>
>     If people cannot change their mind, it is useless to make supporting
>     arguments to nudge them to reconsider.
>
>  (2) I and others may think it is a good idea, a counterargument comes,
>     and people who originally thought it was a good idea may change their
>     mind, and the patch does not go in.  git is saved from becoming
>     worse.
>
>     If people cannot change their mind, it is useless to make counter-
>     arguments to nudge them to reconsider.

Yes, people can change their mind, but if they do so, they must tell
it as it is, and you didn't:
  I think a "Getting started" section that only covers "git config" looks
  way out of place in the beginning of this document.

If you would have said it properly "I've changed my mind" there's an
obvious question that arises: Why? What made you change your mind. You
didn't say that either.

> Yes, I originally thought a "getting started" section may be a good idea.
> There is no need to point it out to me.

One never knows =/

> But after I saw that the original author said "_if_ we have to do this,
> keep it short", the comment made me question my previous assumption one
> more time: is it really a good idea to add "getting started", and is it a
> good idea to cover the config command in that section?
>
> After re-reading the first thousand lines of the user manual, I realized
> that the explanation was carefully laid out so that you do not have to be
> taught "git config" in the beginning to be able to follow it.  Now, after
> applying your latest patch, if we do not have to teach "config" there,
> what else is left in the section? --- Nothing.
>
> What conclusion do you expect me to reach after such a consideration,
> other than "then let's not have it"?

Aha! That's the explanation I was looking for, and what I think you
should have said in the first place. Now we can do some productive
discussion.

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.

Supposing that color.ui is 'auto' by default, then yeah, I don't see
the point of such a "git config" section so early in the document, but
it must be explained somewhere.

>> If you read the results of the last git survey you'll see that the
>> area that needs most improvement is the documentation.
>
> Yes, I did read it, but what about it?  You already know we both want to
> have a good set of documentation.
>
> Remember that "changing" and "improving" is different; some changes may
> not necessarily be improvements.  "It needs improving, so let's change it"
> is not an argument.  This isn't obviously limited to the documentation but
> also applies to UI changes.

No, but "improving" needs "changing", and the discussion I see is
biased towards "not changing".

>> Also I still
>> see many people doing commits without configuring the user name and
>> email properly and so I've tried very hard to improve the user manual
>> to make it easier for them to understand they must do that.
>
> The "unconfigured user.name is wrong" is the least of the problems for
> people who start commiting without understanding the basic principles.
> People may ask "how do I publish my changes", "how do I discard the
> commit" and "how do I modify the commit two days ago", and teaching them
> things like "reset HEAD^" and "rebase -i", without making them aware of
> the implications will do disservice to them in the long run.  That kind of
> self-teaching is already done by people (and for doing so sometimes they
> hurt themselves) by diving into man pages of individual commands before
> understanding the distributedness and its implications, and my hope has
> always been to keep the user-manual a document that teaches things in one
> coherent and hopefully the most useful order.

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.

> The early part of the manual (the first thousand lines) does not talk
> about making commits but lays out the groundwork for a good reason.  And
> in order to follow the current structure of the manual, you do not need to
> be taught "config" as the first thing.
>
> It is a totally different story if we are going to rewrite the manual in
> such a way that we start from "hello world".  I am not necessarily saying
> it is a bad way to teach [*1*].
>
> But the current "starting from a sightseer, while learning the basic
> concepts like reachability and stuff, and then learn to build on top of
> others' work" structure would also be a valid way to teach, and in that
> presentation order, I do not think teaching "config" sits well at the
> beginning.

IMO the vast majority of git users will use it to just fetch a
repository, and browse through it, and that's because most people are
not developers. Even developers most probably will start that way, and
only start committing after a while.

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. Judging from the luck I've had pushing even the simplest
changes I don't think it will improve much more, unfortunately.

Cheers.

-- 
Felipe Contreras