Re: [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`

From: Julia Evans <julia@jvns.ca>
Date: Aug 28, 2025, 18:24 UTC
Message-ID: <006b2c3e-9d73-4781-980c-56f98121b9ed@app.fastmail.com>
In-Reply-To: <xmqq349bxxeu.fsf@gitster.g>

> My assumption was that you are making this a manual to teach what
> "switch to branch" means to folks who do not know, hence my
> question.

Thanks for bringing this up, I think the question of audience is very important.

My main goal right now is actually to make the Git documentation understandable for existing Git users who have already been using Git for at least a year or two. From the feedback I'm getting so far, the man pages are very hard to understand for those users, and even for many users who have been using Git for 10+ years.

The reason that I've been thinking of "existing Git users" and not "newcomers to Git" as the primary audience are:

a) existing users are likely to be the main users of the man pages (after all, beginners don't _stay_ beginners for very long!) b) my impression is that the Git documentation always aims to explain everything in a way that's "completely technically accurate" (which I think makes sense!), and I I think it's often impossible to give a completely technically accurate explanation in a way that a newcomer to Git can completely understand.

That said, of course I'm not against making things accessible to newcomers :) My usual approach in technical writing is to think of "a user who's been using this software for a couple of years already" as the _primary_ audience, but also to try to keep it as accessible to a newcomer as possible.

I think I can figure out how to say something about what it means to "Switch branches" that a newcomer to Git might understand, though of course it'll need to be quite different than the current explanation (existing users generally don't understand what "HEAD" or the "index" are, so a newcomer likely won't understand those terms either).