Git manuals
- From
Petr Baudis <pasky@suse.cz>
- Date
- Nov 19, 2006, 17:59 UTC
- Message-ID
- <20061119175952.GX7201@pasky.or.cz>
- In-Reply-To
- <20061119175040.GB15608@fieldses.org>
On Sun, Nov 19, 2006 at 06:50:40PM CET, J. Bruce Fields wrote:
Show 6 quoted lines
> 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.)
Show 8 quoted lines
> 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."