Re: Outdated and broken online versions of user-manual.html

From: Jonathan Nieder <jrnieder@gmail.com>
Date: May 20, 2013, 07:24 UTC
Message-ID: <20130520072439.GF2919@elie.Belkin>
In-Reply-To: <BE32A698F2774BD5B5235264B13A46C8@PhilipOakley>

Philip Oakley wrote:

> From: "Thomas Ackermann" <th.acker@arcor.de>

>> (5) Large overlapping with the tutorials. IMHO all of the
>> tutorials should be blended into user-manual

[...]

> I would be a little cautious of your point 5 if it squoze everything into
> one overlong document at the expense of losing the shorter documents - one
> can't eat a whole melon in one bite ;-)

Yes.

Once there was a lovely file at

	Documentation/howto/isolate-bugs-with-bisect.txt

explaining how to use "git bisect" to find which commit caused a kernel regression. That it was a small independent file that didn't assume the reader had read much before was very helpful, since it meant people could easily point novices to that page and say "It's easy!" when asking them to track down a bug.

Nowadays that content is gracefully included in the user-manual under the heading [[using-bisect]]. But I never point people to it any more; I just write out the steps by hand, to avoid intimidating them.

Ideally this content would be in an EXAMPLE or TUTORIAL section of the git-bisect(1) manpage for easier reference.

Thanks, Jonathan