From: Julia Evans Date: Wed, 07 Oct 2026 19:29:51 GMT Subject: Re: [PATCH v2] doc: use `man git` to teach users how to navigate the docs Message-ID: <3a665230-b221-410b-9a58-96c01210aea0@app.fastmail.com> In-Reply-To: On Wed, Oct 7, 2026, at 3:13 PM, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" writes: > >> From: Julia Evans >> >> 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. Thanks, can do. Here's my thought process: - 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. - 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. - Once all the others were removed it seemed a bit out of place to mention `gitdatamodel`.