Re: [doc] User Manual Suggestion

["J. Bruce Fields" <bfields@fieldses.org>]

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@fieldses.org> 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.