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

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

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

> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> Reworded the getting started section based on comments from Michael J Gruber,
>> Jonathan Nieder and Junio C Hamano.
>
> Hmm, I thought JBF also had some input...

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.