From: David Abrahams Date: Fri, 24 Apr 2009 04:06:12 GMT Subject: Re: [doc] User Manual Suggestion Message-ID: In-Reply-To: <20090424022900.GB6321@fieldses.org> 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 >> 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