Re: [doc] User Manual Suggestion

From: David Abrahams <dave@boostpro.com>
Date: Apr 23, 2009, 21:31 UTC
Message-ID: <B873CD38-2CFE-4138-8A77-8957FA3DB81C@boostpro.com>
In-Reply-To: <b4087cc50904231345x2613308eh640e50f4a2680890@mail.gmail.com>

On Apr 23, 2009, at 4:45 PM, Michael Witten wrote:

Show 29 quoted lines

> On Thu, Apr 23, 2009 at 15:16, Jeff King <peff@peff.net> wrote:
>> 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". 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 ;) ).
>
> I think the main problem, then, is that the tools have a UI that is
> somewhere in the middle.

Well, "the UI" (how many do we really have for Git?) is spread across the spectrum. The git command-line alone lets you do incredibly low- level things that "nobody should ever do" and some really high-level things that are everyone's bread-and-butter. There's no obvious distinction.

Show 5 quoted lines

> However, a discussion of blobs, trees, commits, objects, and
> references isn't necessarily low-level. It seems to me that it is a
> high-level understanding of the git world. Without those
> *definitions*, people are left to their own wrong, inconsistent
> thoughts.

1000% agreed.

> The low-level stuff is HOW those concepts have been used in the
> implementation of git: Where certain files are stored, how certain
> bytes are organized in memory, what are the underlying porcelain
> tools, etc. That what's low-level.

Yep

Show 7 quoted lines

>> 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.
>
> Maybe I'll try to write something, but it won't take place quickly,
> either. I'd want to read ALL of the existing documentation first.

See you in a couple years ;-)

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