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. 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. 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. And I agree that I haven't succeeded at that--patches welcomed, including patches that, say, move more of the current chapter 7 to an earlier place. (But this has to be done carefully, and I'd still rather it not be the *very* first thing.) I've unfortunately had a lot less time to work on this, but am happy to at least help review patches. --b. -- 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