From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>
Cc: "Julia Evans" <gitgitgadget@gmail•com>, git@vger•kernel.org
Subject: Re: [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>`
Date: Thu, 28 Aug 2025 14:24:30 -0400 [thread overview]
Message-ID: <006b2c3e-9d73-4781-980c-56f98121b9ed@app.fastmail.com> (raw)
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).
next prev parent reply other threads:[~2025-08-28 18:24 UTC|newest]
Thread overview: 68+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-08-25 19:08 [PATCH 0/5] doc: git-checkout: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-25 19:08 ` [PATCH 1/5] doc: git-checkout: clarify intro Julia Evans via GitGitGadget
2025-08-26 18:46 ` Junio C Hamano
2025-08-26 18:51 ` Junio C Hamano
2025-08-26 20:56 ` Julia Evans
2025-08-28 14:00 ` D. Ben Knoble
2025-08-28 22:34 ` Julia Evans
2025-08-28 23:44 ` Junio C Hamano
2025-08-29 13:39 ` D. Ben Knoble
2025-08-29 21:00 ` Junio C Hamano
2025-09-03 23:48 ` D. Ben Knoble
2025-08-25 19:08 ` [PATCH 2/5] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-08-26 21:38 ` Junio C Hamano
2025-08-28 12:11 ` Julia Evans
2025-08-28 15:45 ` Junio C Hamano
2025-08-28 18:24 ` Julia Evans [this message]
2025-08-25 19:08 ` [PATCH 3/5] doc: git-checkout: don't use "reset" Julia Evans via GitGitGadget
2025-08-25 19:08 ` [PATCH 4/5] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-08-25 19:08 ` [PATCH 5/5] doc: git-checkout: clarify restoring files section Julia Evans via GitGitGadget
2025-08-26 22:43 ` Junio C Hamano
2025-08-28 13:26 ` Julia Evans
2025-08-28 19:08 ` D. Ben Knoble
2025-08-28 19:59 ` Julia Evans
2025-08-28 20:38 ` Junio C Hamano
2025-08-29 13:48 ` D. Ben Knoble
2025-08-29 11:45 ` [PATCH v2 0/5] doc: git-checkout: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-08-29 11:45 ` [PATCH v2 1/5] doc: git-checkout: clarify intro Julia Evans via GitGitGadget
2025-08-29 15:58 ` Junio C Hamano
2025-09-02 17:14 ` Julia Evans
2025-08-29 11:45 ` [PATCH v2 2/5] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-08-29 16:03 ` Junio C Hamano
2025-09-02 17:16 ` Julia Evans
2025-08-29 11:45 ` [PATCH v2 3/5] doc: git-checkout: don't use "reset" Julia Evans via GitGitGadget
2025-08-29 16:22 ` Junio C Hamano
2025-09-01 14:28 ` Julia Evans
2025-09-02 16:10 ` Junio C Hamano
2025-08-29 11:45 ` [PATCH v2 4/5] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-08-29 11:45 ` [PATCH v2 5/5] doc: git-checkout: clarify restoring files section Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 1/6] doc: git-checkout: clarify intro Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 2/6] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-09-03 16:49 ` [PATCH v3 3/6] doc: git-checkout: clarify `-b` and `-B` Julia Evans via GitGitGadget
2025-09-03 16:50 ` [PATCH v3 4/6] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-09-03 16:50 ` [PATCH v3 5/6] doc: git-checkout: split up restoring files section Julia Evans via GitGitGadget
2025-09-03 16:50 ` [PATCH v3 6/6] doc: git-checkout: clarify " Julia Evans via GitGitGadget
2025-09-03 21:29 ` Junio C Hamano
2025-09-03 21:09 ` [PATCH v3 0/6] doc: git-checkout: clarify DESCRIPTION section Junio C Hamano
2025-09-03 21:28 ` Julia Evans
2025-09-10 19:14 ` [PATCH v4 0/7] " Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 1/7] doc: git-checkout: clarify intro sentence Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 2/7] doc: git-checkout: clarify ARGUMENT DISAMBIGUATION Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 3/7] doc: git-checkout: clarify `git checkout <branch>` Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 4/7] doc: git-checkout: clarify `-b` and `-B` Julia Evans via GitGitGadget
2025-09-29 18:07 ` Kristoffer Haugsbakk
2025-10-02 18:37 ` [PATCH] doc: git-checkout: fix placeholder markup kristofferhaugsbakk
2025-10-16 22:11 ` [PATCH resend] " kristofferhaugsbakk
2025-10-17 13:56 ` Julia Evans
2025-10-17 15:50 ` [PATCH v2] " kristofferhaugsbakk
2025-09-10 19:14 ` [PATCH v4 5/7] doc: git-checkout: deduplicate --detach explanation Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 6/7] doc: git-checkout: split up restoring files section Julia Evans via GitGitGadget
2025-09-10 19:14 ` [PATCH v4 7/7] doc: git-checkout: clarify " Julia Evans via GitGitGadget
2025-09-11 13:01 ` [PATCH v4 0/7] doc: git-checkout: clarify DESCRIPTION section Ben Knoble
2025-09-12 14:05 ` Julia Evans
2025-09-12 14:26 ` Kristoffer Haugsbakk
2025-09-15 23:22 ` Junio C Hamano
2025-09-16 6:41 ` Kristoffer Haugsbakk
2025-09-12 16:23 ` Junio C Hamano
2025-09-17 18:38 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=006b2c3e-9d73-4781-980c-56f98121b9ed@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox