Re: [PATCH 0/3] [doc] Remove gittutorial-2

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

"Julia Evans" <julia@jvns.ca> writes:

> 3. 22 people who are new to Git have tested the new draft so far
> 3.1. Several of the testers said in the post-tutorial survey that they wanted more
>    information on branching and collaboration with Git. This was the most common
>    "what do you wish this tutorial covered?" request.
> 3.2. Several of the testers also said that the new version is a lot of
>    material, and they were not able to finish it because they didn't have time
> 4. Writing tutorial material is a lot of work, it will take time to do a good
>    job of covering branching and collaboration

Good info to share more widely around here.

> It's important for us to cover branching, collaboration, and how to restore
> old work in our tutorial material.

OK.

> option 1: Refer folks to the contents of the current `gittutorial` (in some new
> location?) to learn branching and collaboration. I think this is what you are
> suggesting (?).

Not at all.  If the material in the existing document is inadequate,
after examining why it is inadequate (e.g., perhaps it assumes
certain prerequisite knowledge or work experience that today's new
users are unlikely to have), we decide if we can salvage it or we
need to write from scratch.  It is very likely that it is the latter
case---otherwise we wouldn't be having this conversation to begin
with.

> option 2: Ship the new tutorial without a guide to branching and collaboration,
> with that to come later. Not ideal, but I think this is better than option 1,
> since at least we are not pointing users to a tutorial that we know will not
> help them.

I think this, #1, and #3 are essentially different sides of the the
same coin.  If gittutorial can fill the gap, we use it as a stop-gap
measure while we prepare a better one.  If it is so bad that it
would contaminate new users' minds, and they are better off learning
the hard way from more technical documentation and external books
instead of tutorial, we won't give them any stop-gap.  We may or may
not have external material we can recommend.