On Thu, Apr 23, 2009 at 15:16, Jeff King <peff@xxxxxxxx> 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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html