Re: [doc] User Manual Suggestion

[Jeff King <peff@peff.net>]

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

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

> 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