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

[Junio C Hamano <gitster@pobox.com>]

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, I originally thought a "getting started" section may be a good idea.
There is no need to point it out to me.

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

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

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

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.


[Footnote]

*1* Indeed, the book I did recently does just that, starting from a solo
user who develops on his own from scratch, and then uses another
repository as a back up repository, and then works on two different
machines with a repository each, still working solo no the same project.
After that working with other users collaboratively comes. If you teach in
that order, you have to cover config before you cover commit, which pretty
much means config is mentioned at the very beginning.