Subject: Re: Git manuals

From: "J. Bruce Fields" <[email-masked]>
Date: Sun, 19 Nov 2006 14:36:09 -0500

On Sun, Nov 19, 2006 at 06:59:52PM +0100, Petr Baudis wrote:
> On Sun, Nov 19, 2006 at 06:50:40PM CET, J. Bruce Fields wrote:
> > In fact, I'm tempted to submit a patch that just assigns a chapter
> > number to everything under Documentation/, slaps a single table of
> > contents on the front, and calls the result "the git user's manual."
> > 
> > Of course, the moment people started trying to read the thing they'd
> > complain that it was a mess--some stuff referenced without being
> > introduced, other stuff introduced too many times.  But then over time
> > maybe that'd force us to mold it into some sort of logical sequence.
> 
> Sequencing isn't the only problem. A _manual_ is different from
> _reference documentation_ in that it does not usually describe command
> after command, but rather concept after concept. So instead of slamming
> git-*-pack commands together, you have a section "Handling Packs" where
> you try to coherently describe the commands together.
> 
> Your approach is fine for something you would call "Git Reference
> Manual", but it is something really different from "The Git Book" or
> "Git User's Manual".

Yeah, of course, but I wasn't actually thinking of the man pages so much
as:
	everyday.txt
	tutorial.txt
	tutorial-2.txt
	core-tutorial.txt
	howto/
	hooks.txt
	README
	glossary.txt

etc.