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

["Julia Evans via GitGitGadget" <gitgitgadget@gmail.com>]

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(-)

diff --git a/Documentation/git.adoc b/Documentation/git.adoc
index 6f0075f918..6dfb829a7e 100644
--- a/Documentation/git.adoc
+++ b/Documentation/git.adoc
@@ -22,21 +22,21 @@ Git is a fast, scalable, distributed revision control system with an
 unusually rich command set that provides both high-level operations
 and full access to internals.
 
-See linkgit:gittutorial[7] to get started, then see
-linkgit:giteveryday[7] for a useful minimum set of
-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.
+- `git push -h` for a short help
+- `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.
 
 OPTIONS
 -------

base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220
-- 
gitgitgadget