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

Junio C Hamano <gitster@pobox.com> writes:

Ah, nevermind. Yes, he did have input, and I tend to agree with him, and more importantly trust his judgement on the manual.

I think a "Getting started" section that only covers "git config" looks way out of place in the beginning of this document.

Manuals by other people that teach "here is how you would do a hello-world repository" would want to teach user.name before reaching that point, but because the user-manual is written in such a way that it first introduces concepts to understand what is going on without changing anything, we do not have much need user.name until it gets to "Developing with git" section.

"Many people prefer to teach it this way" does not justify "everybody must teach it this way" an iota, when teaching "config user.name" upfront will fit the flow of how they teach but does not fit the flow of how this manual teaches [*1*].

I'm inclined to to discard the first patch.

The point of the original text the second patch touches was to show how simple the contents of the configuration file is and give the users that there is nothing magic there. While I do not like the second patch as-is, because it destroys that nice property and treats the end users mindless "cut-and-paste without thinking" sheeples, I think that it is rather vague and unhelpful to the current target audience to say:

    ...  The easiest way to do so is to make sure the following lines
    appear in a file named .gitconfig in your home directory:

and the parts can use some improvement. For example, "home directory" does not hold true for people on platforms that lack the concept. Keeping the current "the following lines appear", rewording "in a file named .gitconfig in your home directory" with "in your per-user configuration file", keeping the display that shows how the config snippet should look like, and using "config --global -e" might be a better approach.

[Footnote]

*1* Unless you are changing the flow of how this manual teaches at the same time, that is. And no, I am not suggesting that we should start from "let's do a hello-world repository from scratch". I think the current "start from read-only and then learn how to grow history later" is one valid way to teach.