Re: [doc] User Manual Suggestion

[Michael Witten <mfwitten@gmail.com>]

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.