Re: [doc] User Manual Suggestion

[Michael Witten <mfwitten@gmail.com>]

On Fri, Apr 24, 2009 at 10:04, Jeff King <peff@peff.net> wrote:
> 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.

Indeed. I saw that last sentence of yours, but I consciously ignored
it, because I like to argue ;-)

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

That, my friend, is the most important lesson of learning.

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

I think that we've already got that tutorial-esque style covered (I
haven't read it in a while):

    http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html

However, the User Manual should make a Mathematician happy.

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

Actually, those commit orbits are defined by the giant glass sphere to
which they are attached.