Re: [doc] User Manual Suggestion

From: David Abrahams <dave@boostpro.com>
Date: Apr 23, 2009, 21:26 UTC
Message-ID: <D912CAB9-E437-4733-8A87-97EE47E3FBBB@boostpro.com>
In-Reply-To: <20090423201636.GD3056@coredump.intra.peff.net>

On Apr 23, 2009, at 4:16 PM, Jeff King wrote:

Show 15 quoted lines

> On Thu, Apr 23, 2009 at 01:37:05PM -0500, Michael Witten wrote:
>
>> 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".

And that's a problem because so many things are badly named. It also leaves out lots of top

> There are
> some "bottom-up" resources available, but I haven't seen one pointed  
> to
> as "definitive".

I've been pointed at:

1. http://eagain.net/articles/git-for-computer-scientists
2. http://www.newartisans.com/2008/04/git-from-the-bottom-up.html

which, IMO, should be read in that order. I've just sent John Wiegley a huge pile of editorial commentary on #2, which I think could improve things.

But that said, "laying conceptual foundation" doesn't imply bottom- up! In fact, I don't think the first one is particularly bottom-up

-- David Abrahams BoostPro Computing http://boostpro.com