Re: [doc] User Manual Suggestion

From: Jeff King <peff@peff.net>
Date: Apr 23, 2009, 20:16 UTC
Message-ID: <20090423201636.GD3056@coredump.intra.peff.net>
In-Reply-To: <b4087cc50904231137g67b4b84eu3b61bf174ba37d7f@mail.gmail.com>

On Thu, Apr 23, 2009 at 01:37:05PM -0500, Michael Witten wrote:

Show 9 quoted lines

> Everyone talks about "before one has the conceptual foundation
> necessary to understand". Well, here's an idea: The git documentation
> should start with the concepts!
> 
> Why don't the docs start out defining blobs and trees and the object
> database and references into that database? The reason everything is
> so confusing is that the understanding is brushed under the tutorial
> rug. People need to learn how to think before they can effectively
> learn to start doing.

I agree with you, but not everyone does (and you can find prior debates in the list archives). The user-manual is pretty "top down". There are some "bottom-up" resources available, but I haven't seen one pointed to as "definitive". I think it might actually be nice for there to be a parallel to the user manual that follows the bottom-up approach, and people could read the one that appeals most to them (or if they have a lot of time on their hands, read both and hopefully it makes sense in the middle ;) ).

But we would need somebody to volunteer to write it. I would be happy to help out, but I'm too short on time at the moment to be the driving force.

-Peff