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

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

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

> 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.

The text mentions removing 'tutorial' and 'everyday', but does
not explain why we no longer reference 'user-manual', 'datamodel',
and 'cli'.  The third iteration should justify this.  At least,
I recall that adding a reference to 'cli' early in the document was
a deliberate decision, and we should explain why it is no longer
relevant.  It would not be surprising if it has become obsolete
over the last decade, but we still need to spell out why it is no
longer appropriate to reference here.

I wholeheartedly agree with dropping 'everyday', which was written
before Git 1.0 back when we did not have much introductory material.
It was not aspirational, and while its choice of twenty commands
suited the workflows of the time, it outlived its usefulness long
ago.

Thanks.