[PATCH] [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
    
    Here's a list of things I'm still considering in the hopes that it'll
    help with the discussion:
    
    I'm not totally satisfied with the description of git help
    --user-interfaces here. It might be clearer to give examples of topics
    those guides cover, like "hooks, .gitignore, and more".
    
    I thought about mentioning git help push and/or man git-push, but (from
    a Mastodon survey I did) git push --help is the one users are most
    familiar with, it's most similar to how other Unix tools work, and it
    makes the description really clear and concise (-h for short help,
    --help for long help).
    
    We just added gitdatamodel here but I took it out because I couldn't
    find a place to put it in the new explanation that felt natural. I do
    think that discoverability of that guide is still an issue and it's
    something that's on my mind. One option in the future to make the guides
    more discoverable would be to feature them more often in Git's advice,
    for example see 'git help mergeconflicts' for a guide to handling merge
    conflicts. Users definitely do read the advice.
    
    Related to the discussion here
    https://lore.kernel.org/git/7004c3b1-2100-4a90-9815-2a679ceb25b2@app.fastmail.com/T/#mf600063180d6239916e3fa6e9d33da86969547ec
    
    ccing Kristoffer who edited this most recently.

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

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