Re: [doc] User Manual Suggestion

[Michael Witten <mfwitten@gmail.com>]

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.

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.

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.

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