On Sun, Nov 19, 2006 at 06:50:40PM CET, J. Bruce Fields wrote:
quoted text
> On Fri, Nov 17, 2006 at 01:21:57PM -0500, bfields wrote:
> > On Fri, Nov 17, 2006 at 10:32:46AM -0500, Theodore Tso wrote:
> > > It would be nice if there was an easy way to direct users through the
> > > documentation in a way which makes good pedagogical sense.
> ....
> > How about this as a strawman "git user's manual" outline:

(I was briefly discussing Git Book with Junio at OLS, I think the result
was "yeah, would be nice, perhaps we can start poking it soon". I
started to think about it once again in the last few weeks.)

quoted text
> 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".

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
The meaning of Stonehenge in Traflamadorian, when viewed from above, is:
"Replacement part being rushed with all possible speed."
		-- Kurt Vonnegut, Sirens from Titan
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html