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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Oct 24, 2009, 20:16 UTC
Message-ID: <94a0d4530910241316r3fc4136emd036d18aa45a4192@mail.gmail.com>
In-Reply-To: <7vr5ss64e5.fsf@alter.siamese.dyndns.org>

On Sat, Oct 24, 2009 at 9:19 PM, Junio C Hamano <gitster@pobox.com> wrote:

Show 11 quoted lines

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

JBF said this[1]: If we have to do this, just keep it short....

And I am trying to keep it short.

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

Now you are saying that the fact that it's short is a bad thing? That goes against to what JBF said.

And let's not forget your previous comments

[2]: I think a "getting started" section near the beginning of the manual is a good idea (and ll.40- is a very early part of the manual).

[3]: I actually wish this section appeared a lot earlier in the document, but that is a separate issue.

Show 11 quoted lines

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

Nobody argued that "everybody must teach it this way", the argument was that most people find it easier, and considering the section is about "developing with git" it is sensible to avoid burdening the reader with concepts that don't pertain to the objective at hand, which is getting them to configure their user.

And let's not forget that the current text is broken for Windows users.

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

Show 5 quoted lines

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

What's wrong with teaching one thing at a time? Configuring the user is something so essential, I don't think it makes sense to make the task difficult on purpose. Some people might avoid doing it precisely because of that.

Show 12 quoted lines

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

If you read the results of the last git survey you'll see that the area that needs most improvement is the documentation. 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. In the process I've added the --edit option to 'git config' and the new "getting started" section, in order to address all the issues mentioned in previous threads and gone through several iterations of these patches already.

I'm starting to think that all the previous "constructive" feedback was actually targeted to deter people from making any changes.

I'm CC'ing people that have been involved in previous threads.

Show 7 quoted lines

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

I also don't think the flow should be changed, that's why I didn't put the user configuration on the "getting started" section. It goes into the "developing with git" section.

[1] http://article.gmane.org/gmane.comp.version-control.git/130236 [2] http://article.gmane.org/gmane.comp.version-control.git/115649 [3] http://article.gmane.org/gmane.comp.version-control.git/106667

-- 
Felipe Contreras