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

[Junio C Hamano <gitster@pobox.com>]

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.

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.