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

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