[PATCH v3] 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>

Rewrite `man git` to give a more realistic view of what the
documentation actually provides.

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 direct references to all the guides, for the following
reasons:

* gittutorial and giteveryday are 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.

  The goal is to mention the tutorial again when when we have a tutorial
  we're happy with.
* gitcli is not very useful for users. A lot of it is about scripting
  and internal details about the option parser.
* the user manual is outdated. The chapter on "Sharing development with
  others" explains how to use `git format-patch` which is not how most
  Git users collaborate with git.
* mentioning the data model feels out of place once everything else is
  removed

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

Mention `git help --guides` and `git help --user-interfaces`,
since there are some important guides in there (like `submodules`) that
are hard to discover.

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

Remove https://git.github.io/htmldocs/git.html since it points to the
`master` version of the documentation. https://git-scm.com/ has the
version from the latest release which is more likely to be useful.

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])
    
    Changes in v3: (just updates to the commit message)
    
     * Add a sentence summarizing the goals "give a more realistic view of
       what the documentation actually provides."
     * Explain why we're removing https://git.github.io/htmldocs/git.html,
       gitcli, and the user manual, and the data model
     * Mention the plan to include the tutorial again here once we have one
       we're happy with

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

Range-diff vs v2:

 1:  18f373a8f3 ! 1:  6cb4390e53 doc: use `man git` to teach users how to navigate the docs
     @@ Metadata
       ## Commit message ##
          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`
     -    doesn't make it easy to find out how to get help with using Git.
     +    Rewrite `man git` to give a more realistic view of what the
     +    documentation actually provides.
      
          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.
     +    Remove the direct references to all the guides, for the following
     +    reasons:
     +
     +    * gittutorial and giteveryday are 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.
     +
     +      The goal is to mention the tutorial again when when we have a tutorial
     +      we're happy with.
     +    * gitcli is not very useful for users. A lot of it is about scripting
     +      and internal details about the option parser.
     +    * the user manual is outdated. The chapter on "Sharing development with
     +      others" explains how to use `git format-patch` which is not how most
     +      Git users collaborate with git.
     +    * mentioning the data model feels out of place once everything else is
     +      removed
      
          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.
     +    Mention `git help --guides` and `git help --user-interfaces`,
     +    since there are some important guides in there (like `submodules`) that
     +    are hard to discover.
      
          Do not mention `git help --developer-interfaces` since it's not relevant
          to users.
      
     +    Remove https://git.github.io/htmldocs/git.html since it points to the
     +    `master` version of the documentation. https://git-scm.com/ has the
     +    version from the latest release which is more likely to be useful.
     +
          Signed-off-by: Julia Evans <julia@jvns.ca>
      
       ## Documentation/git.adoc ##


 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