On Apr 23, 2009, at 4:45 PM, Michael Witten wrote:
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.
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.
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
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
--
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