Git manuals

On Sun, Nov 19, 2006 at 06:50:40PM CET, J. Bruce Fields wrote:

On Fri, Nov 17, 2006 at 01:21:57PM -0500, bfields wrote:

quoted

On Fri, Nov 17, 2006 at 10:32:46AM -0500, Theodore Tso wrote:

quoted

It would be nice if there was an easy way to direct users through the
documentation in a way which makes good pedagogical sense.

....

quoted

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.)

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