From: Junio C Hamano Date: Fri, 13 Nov 2026 21:56:49 GMT Subject: Re: [PATCH v4] doc: checkout: rewrite detached HEAD state explanation Message-ID: In-Reply-To: Julia Evans 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.