Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation

[Julia Evans <julia@jvns.ca>]

On 2026-11-13 4:56 p.m., Junio C Hamano wrote:
> Julia Evans <julia@jvns.ca> writes:
>
>> Of course these are both important audiences, but it's always hard to
>> write a document for two very different audience at the same time. For
>> example, one thing that came up in this thread is that creating commits
>> while not on a branch is a problem for the first person and a good thing
>> for the second person.
> This is a manual page, which means it has to cater to both audiences.
> Unlike a tutorial or guide, we cannot say we target this audience
> primarily and expect the other audience to figure things out
> themselves.

My main goal with this patch series was really to create a new guide 
that we can reference as `git help detached-head` in our advice to help 
users who are confused by detached HEAD state.

I thought that it would make sense to frame it as as improvement 
to`git-checkout` as well (and that the goals of both sections were 
similar enough that you could easily view the content in both ways), but 
maybe those documents actually do have fairly different goals and it's 
too difficult to do that.

I can remove the changes to `git-checkout.adoc` and reframe the series 
from the point of view of "we want to help users who are confused by 
detached HEAD state", it's an easy change.

> To cover the "oops, I got myself into a problem?  I do not even know
> if I am in trouble, or if Git is behaving as expected, and I am
> totally lost.  I do not even know which commands I typed in the last
> 5 minutes got me into this state" situation, manual pages that are
> organized along commands to help quick look-up are a bad match.
>
> Perhaps a FAQ or "survival guide" that targets these inexperienced
> users would help?  Unlike manual pages, guides have more freedom in
> choosing the material covered and the order in which they are
> presented.  I dunno.