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

Felipe Contreras <felipe.contreras@gmail.com> writes:

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

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.

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.