[PATCH v2] doc: use `man git` to teach users how to navigate the docs

From: Julia Evans <julia@jvns.ca>

Many existing users of Git don't know how Git's documentation is structured, and a lot of folks have expressed frustration that `man git` doesn't make it easy to find out how to get help with using Git.

Explain how Git's help system works in `man git` (`git push -h` gives a short help, `git push --help` is the full docs), since it's a slightly unusual approach.

Remove the references to gittutorial and giteveryday since they're unlikely to help new users learn Git. Currently they feel very aspirational (it would be nice to have a tutorial and a guide to everyday Git commands!), but we should give users a realistic view of what the documentation actually provides.

Mention `git help` instead of `giteveryday` for now, which does a better job of giving an overview of everyday commands.

Also mention `git help --guides` and `git help --user-interfaces`, since those parts of the documentation are useful and hard to discover.

Do not mention `git help --developer-interfaces` since it's not relevant to users.

Signed-off-by: Julia Evans <julia@jvns.ca>
---
    [doc] Use man git to teach users how to navigate the docs
    
    Changes in v2:
    
     * mention the git help push form too
     * mention you can get HTML docs with git help --web push at the end to
       advertise git help's great features, and remove
       https://git.github.io/htmldocs/git.html since
       https://git-scm.com/docs has a nicer view and 3 different options is
       a lot.
     * some minor wording changes
     * fix commit message style (doc: not [doc])

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2242%2Fjvns%2Fupdate-git-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2242/jvns/update-git-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2242

Range-diff vs v1:

 1:  5da3881760 ! 1:  18f373a8f3 [doc] Use `man git` to teach users how to navigate the docs
     @@ Metadata
      Author: Julia Evans <julia@jvns.ca>
      
       ## Commit message ##
     -    [doc] Use `man git` to teach users how to navigate the docs
     +    doc: use `man git` to teach users how to navigate the docs
      
          Many existing users of Git don't know how Git's documentation is
          structured, and a lot of folks have expressed frustration that `man git`
     @@ Documentation/git.adoc: Git is a fast, scalable, distributed revision control sy
      -commands.  The link:user-manual.html[Git User's Manual] has a more
      -in-depth introduction.  See linkgit:gitdatamodel[7] if you want to
      -learn about the data model and important terminology.
     --
     ++There are two ways to get help with any Git subcommand (replace "push"
     ++with the command you want help with):
     + 
      -After you mastered the basic concepts, you can come back to this
      -page to learn what commands Git offers.  You can learn more about
      -individual Git commands with "git help command".  linkgit:gitcli[7]
      -manual page gives you an overview of the command-line command syntax.
     -+There are two ways to get help on any Git subcommand (replace "push"
     -+with the command you want help with):
     -+
      +- `git push -h` for a short help
     -+- `git push --help` for the full documentation
     -+
     ++- `git push --help` or `git help push` for the full documentation
     + 
     +-A formatted and hyperlinked copy of the latest Git documentation
     +-can be viewed at https://git.github.io/htmldocs/git.html
     +-or https://git-scm.com/docs.
      +There are also guides explaining Git's concepts and more:
     -+
     + 
      +- `git help` shows the most frequently used Git subcommands
      +- `git help --guides` lists Git's concept guides
      +- `git help --user-interfaces` lists guides for various
      +  special files you can use to change Git's behaviour
     ++
     ++You can view an HTML version of the documentation with `git help --web`
     ++(for example `git help --web push`) or at https://git-scm.com/docs.
       
     - A formatted and hyperlinked copy of the latest Git documentation
     - can be viewed at https://git.github.io/htmldocs/git.html
     + OPTIONS
     + -------

 Documentation/git.adoc | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)