Re: [PATCH v4 2/2] doc: add new Git tutorial for beginners

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

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> Introduce Git in two parts:
>
> Steps 1-7: Create an empty repo & make 2 commits (`git init`,
> `git add`, `git commit`, `git status`, `git diff`)
> Steps 8-12: Push the repo to a remote host like GitHub or GitLab
> (`git remote add`, `git push`)
>
> Some design choices:
>
> - Only use commands present in 2.23.0 (when `git switch` as introduced),
>   to support older versions of Git.
> - Introduce a much smaller set of commands than the old tutorial, to
>   keep the tutorial quick (doable in an hour). Some users found it to be
>   very fast and some wanted to stop early (after step 7) so this seems
>   to be a good balance.
> - Have users start with an empty repository instead of an existing
>   project, because many of the testers did not have an existing project
>   to test, or were scared of using an existing project.
> - Add a troubleshooting section, since in the testing some users got
>   extremely stuck (for 4+ hours) on minor issues like needing to say
>   "yes" when SSHing to a new host.
> - Don't explain branches, because explaining branches and collaboration
>   is complicated and deserves its own tutorial. Instead just tell users
>   we're not going to explain them in this document.
> - Tell users to set their default branch to `main`, because many Git
>   hosts use it as their default branch and it really simplifies things.
> - Keep it as vendor neutral as possible, while acknowledging the reality
>   that Git hosting services like GitHub, GitLab, etc are extremely
>   popular. Do this by creating the repo locally and then optionally
>   pushing it later.
> - Use SSH for authentication, explaining how to set up SSH in the
>   easiest way possible (with disclaimers to check your security team's
>   policy if applicable since the "easiest way" may not be the best), and
>   giving some instructions for how to translate an HTTPS URL to an SSH
>   URL.
> - Use Git Credential Manager for authentication on Windows, since it's
>   simpler, SSH auth is a very "unixy" thing to do,  and it comes with
>   Git for Windows

What does "it" in "and it comes with" refer to?  It is unclear
between GCM or SSH and since SSH appeared later, it tempts readers
to think that it says "and SSH comes with GfW".  But the early part
of the same sentence says SSH is "unixy", which probably was used as
a synonym to "non-Windowsy", implying that we do not want to
recommend it.  It gives a conflicting and confused message.

  - Use GCM for authentication on Windows, since it comes with GfW,
    and is simpler than SSH authentication.

> +Step 10 (Mac/Linux only): Create an SSH key if needed
> +-----------------------------------------------------
> +For Git to upload changes to another Git repository, it needs a way to
> +login to that repository. One of the most popular ways to do this is
> +with an SSH key.
> +
> +On Windows, you can skip this step and the next one because Git for
> +Windows comes with
> +https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager]
> +to handle logging in. 

This is the only mention of GCM.  As described in step 14 (push),
GCM will kick in when needed.  It is great that Windows users do not
need any handholding beyond this line ;-)