Re: [doc] User Manual Suggestion

From: Michael Witten <mfwitten@gmail.com>
Date: Apr 24, 2009, 14:30 UTC
Message-ID: <b4087cc50904240730n42e605e1od37d88d43e00f142@mail.gmail.com>
In-Reply-To: <20090424141139.GC10761@coredump.intra.peff.net>

On Fri, Apr 24, 2009 at 09:11, Jeff King <peff@peff.net> wrote:

Show 6 quoted lines

> 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.