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

["Julia Evans" <julia@jvns.ca>]

> You confuse me.
>
> What do you mean by "it" in "keep it around"?  gittutorial.adoc?
>
> If so you said it yourself, that we want to have a tutorial that
> covers the basics like `git init` etc.
>
> Or do you mean some other document, like gittutorial-2?  It would
> have made sense to keep it while a replacement was being written, to
> make comparison easier, *if* the goal were to make sure that the new
> one covers everything the existing one covered, but we already
> agreed that it is not the goal to salvage what is in gittutorial-2
> (and that is why I personally feel it is OK to remove the old one
> first).

Here's another attempt to explain! I think this whole sub-discussion
is not very relevant to `gittutorial-2` (the subject of this patch series) 
which should be deleted in any case. I would move this out to talk
about it separately but the mailing list is still tough for me to navigate.

Everything after this point is about `gittutorial.adoc` and about how
to manage the process of improving it.

Here are some facts, some of my opinions, and some options I see.
Apologies for the length :)

Facts:

1. The current `gittutorial` covers git init, git add, git commit, git diff, git
   log, git branch, git switch, git merge, git clone, git fetch, git pull, gitk,
   git remote add, git show, git reset --hard, git tag, git show, and git status,
   (and potentially more commands I missed)
2. My current `gittutorial` draft covers fewer topics: just
   git init, git add, git commit, git diff, git status git remote add, git push.
   Basically just how to make commits and push them to a remote.
   These tools on their own are enough for a user to back up their code or use Git to
   publish a website (for instance with Github Pages or Heroku RIP)
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

Opinions:

It's important for us to cover branching, collaboration, and how to restore
old work in our tutorial material. There are other topics too but these are the
most important.

It’s not realistic to expect new Git users to be able to learn what they need to
know about branching and collaboration from the “MANAGING BRANCHES” and “USING
GIT FOR COLLABORATION” sections of `gittutorial`. Two of the many issues are
that it starts talking about branches without explaining what they are, and it
teaches collaboration in the context of a multi-user system which is not how the
vast majority of users would collaborate. As far as I can tell it never explains
what a branch is in any way. My impression is that we all already agree that
this tutorial is not doing the job it needs to do in any case.

It's also probably unrealistic to merge a guide to branching at the same time as
the intro to `git commit` just because it's already so much work just to cover
the first parts effectively.

All of this together means we’re not in an ideal situation.

Options I see for dealing with this:

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 (?). I am not willing to do this because (as mentioned) the current
gittutorial is not a good way to learn those topics.

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.

option 3: Recommend some kind of external guide for now. We talked about this
before and I agree there are issues with maintainability etc.

option 4: Wait until we have a new tutorial on branching to merge any new
tutorial. This will take a very long time and it’ll be a lot more to review at
one time.

Right now option 2 is my preferred one of the options (which all have different
drawbacks)

best,
Julia