Re: [doc] User Manual Suggestion

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