Re: [doc] User Manual Suggestion

From: Jeff King <peff@peff.net>
Date: Apr 24, 2009, 15:04 UTC
Message-ID: <20090424150442.GA11245@coredump.intra.peff.net>
In-Reply-To: <b4087cc50904240730n42e605e1od37d88d43e00f142@mail.gmail.com>

On Fri, Apr 24, 2009 at 09:30:20AM -0500, Michael Witten wrote:

Show 12 quoted lines

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

Heh. I don't think you also predicted the paragraph that I ended up deleting, which made it more clear that I was not trying to rebut, but rather agree.

Like you, I think that not teaching concepts first leads to confusion later. Version control (or at least git) is just complex enough that you are much better off understanding what is happening than simply following a recipe. So when your recipe doesn't go as planned, or you don't know which recipe to use, or you need some variant of a recipe, you have some basis for understanding what to do.

But users in the past have really seemed to want to start with recipes, so that they can be productive as soon as possible (and I think some people have said that the top-down ordering just makes more sense to them, so it may just be a matter of learning style). And I think the user manual is somewhat of a response to that request, since the command manpages are very bottom-up (but are also quite confusing, just because of their size, and because concept information is scattered throughout).

So I am advocating for more bottom-up documentation (which I think you are), but I don't necessarily think it should _replace_ the top-down documentation (which I'm not sure is your position or not).

Show 6 quoted lines

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

Epicycles? I thought commit orbits were defined by the ether through they flowed.

-Peff