On Apr 23, 2009, at 10:29 PM, J. Bruce Fields wrote:
On Thu, Apr 23, 2009 at 01:37:05PM -0500, Michael Witten wrote:
On Thu, Apr 23, 2009 at 12:57, J. Bruce Fields
<bfields@xxxxxxxxxxxx> wrote:
On Wed, Apr 22, 2009 at 03:38:52PM -0400, David Abrahams wrote:
http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#how-to-check-out
covers "git reset" way too early, IMO, before one has the
conceptual
foundation necessary to understand what it means to "modify the
current
branch to point at v2.6.17". If this operation must be covered
this
early in the manual, it should probably not be until
http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#manipulating-branches
I agree; we should suggest just a git-checkout (to a detached HEAD)
instead, though that needs a little explanation so people aren't
scared
by the warning message it gives.
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.
OK, but let's not over-generalize: the person that just wants to
figure
out whether the driver for their network card was fixed in today's
network devel tree shouldn't have to sit through a discussion of the
object database.
Those people don't need a VCS. They should download a snapshot or use
a web interface. Seriously. There's no way you can make even the
best-designed VCS simple enough to justify the time it takes to learn
enough just to use it for that.
And even among readers that are in it for the long
haul, I think many people will react better to something that gives
them
at least a little concrete how-to information up front.
People (well, people like me) should get a brief "hello, world" demo
up front, to give them a feel for the flavor of the system, but
[important:] it shouldn't attempt to be instructive. Fundamental
concepts are next. How-to information can come after that, or after
the reference information.
So the goal was always to find a tutorial route through the material
that would allow us to introduce the concepts as we go along.
Maybe that will work for some people, but it *really* won't work for
me. You can't start throwing around terms of art without defining
them unless you want to raise more questions than you're answering. I
would be surprised if it wasn't the same for many tech people.
--
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