Re: [doc] User Manual Suggestion

[Michael Witten <mfwitten@gmail.com>]

On Fri, Apr 24, 2009 at 09:11, Jeff King <peff@peff.net> wrote:
> I think I wasn't clear in my original message. I didn't mean teaching
> low-level stuff like plumbing or file layouts. By "bottom-up" I really
> meant teaching concepts (like objects, their types, and references),
> from which user operations and workflows can be explained (or often
> deduced by the user). Whereas a top-down approach would _start_ with
> workflows and say "To accomplish X, do Y".

I knew you would make exactly this rebuttle ;-D

However, notice that you can't reasonably be expected to understand
"accomplish X" without having concepts like objects and references.
The reason most people get by is that git's operation can be
compatible with a number of other theories people might have already
picked up from using computers. The trouble starts when their existing
theories don't mesh well with the underlying git theory, leading the
user to develop the equivalent of epicycles in order to explain to
himself whats going on.

Basically, the problem is that the documentation is currently catering
for people, who just want to download source files (as Bruce basically
said); a quick shell synopsis for this is fine, but there needs to be
documentation solely devoted to understanding git fully and precisely.