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

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

"Julia Evans" <julia@jvns.ca> writes:

> - Removed 'cli' because (from my perspective as a user) it seems like
>   something that's written for Git developers and not users, like
>   with "Commands that support the enhanced option parser",
>   how is a user supposed to know which commands support
>   the enhanced parser? I think it makes sense as a guide to
>   scripting Git but not for interactive use. Some of the bits on `diff`
>   feel like they might belong in the `git diff` man page, not sure.

Perhaps updating cli so that it does not give a false smell of
getting written for a wrong audiences is a more productive
direction, though?  I do not think there is any other document that
tells users the simple "options first and then revs and then paths"
rule, for example.

> - Removed "user-manual" because it's outdated. The chapter on
>   "Sharing development with others" explains how to use
>   `git format-patch` which is not how most people collaborate with
>   git.

Yes, the was written in a very early days, and by a person who
worked in the Linux kernel circle.  I do not know about "not how
most people" part, but I would agree that "many users do not use"
would be a fair description of the modern world order.

> - Once all the others were removed it seemed a bit out of place
>   to mention `gitdatamodel`.

Not limited to the issue of where `gitdatamodel` should fit, I think
we probably should explain the goal of these change at a bit higher
level.  The original intention to refer to these things very early
in the documentation was to direct those readers who are not ready
to go into the list of git subcommands to those "introductory" text
and concepts guides, and encourage them to come back once they are
equipped with basic concepts and workflows.  I do not know if that
design actually helped or was harmful for the real-world learners,
but if we are shuffling the material we present early by removing
some and introducing others, we should explain what our overall
design of the presentation order is, for example.

Thanks.