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

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 2, 2026, 07:38 UTC
Message-ID: <xmqqfqyo363i.fsf@gitster.g>
In-Reply-To: <040938c6-6fc9-4727-901a-9be2b0b3a6cf@app.fastmail.com>

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

Show 8 quoted lines

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