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

From: Julia Evans <julia@jvns.ca>
Date: Oct 8, 2026, 15:09 UTC
Message-ID: <b121896e-03d9-498f-9fe3-6688c4ff4034@app.fastmail.com>
In-Reply-To: <xmqq4iex6zox.fsf@gitster.g>

On Wed, Oct 7, 2026, at 4:08 PM, Junio C Hamano wrote:

Show 15 quoted lines

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

If at some time in the future we update `gitcli` I think it could make sense to put it back!

Show 24 quoted lines

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

As we rebuild some of this intro material we can bring it back in. For example once we have a tutorial we're happy with I think it would make sense to suggest that folks read it to learn Git.

If you're asking what I intend the overall design of the presentation order to be, the goal is to bring the Git docs towards more of an "every page is page one" design https://everypageispageone.com/the-book/ where on most pages we don't expect or require the reader to have read any of the other documentation. So for the the most part there would be no "presentation order". We'd instead provide links to more context for people who are interested. This increased focus on linking is why I sent that patch to make the AsciiDoc links work better in the HTML docs.

I think this kind of "every page is page one" structure would be both easier to maintain and better matches what users want than a book like the user manual, so it's a win/win.

In some cases (like the tutorial) I think it would make sense to have an order, like "learn `git commit` before learning branching", but I think we should keep those sequences very short. Ideally we would be able to get feedback from folks learning Git from the tutorial to find out they would like to learn next.