Re: [doc] User Manual Suggestion

[Johan Herland <johan@herland.net>]

On Friday 24 April 2009, Michael Witten wrote:
> On Thu, Apr 23, 2009 at 17:51, Johan Herland <johan@herland.net> wrote:
> > There's also http://www.eecs.harvard.edu/~cduan/technical/git/ which I
> > think is a great bottom-up introduction:
> > - not too heavy on the concepts
>
> I really don't understand this mentality. Concepts are the only things
> that are important. From concepts falls all else.

Sorry for not being clear: Concepts are indeed (and should be) important. 
What I mean is that the concepts introduced are short and simple enough for 
novice users to understand (without much VCS experience, if any at all). If 
we start off _too_ detailed, we risk loosing the audience, and no one is 
better off.

Like Jeff King said elsewhere in this thread: We want to start a little 
higher from the bottom. The above introduction does not focus on blobs or 
trees, but manages to introduce Git in a useful manner by starting off with 
only two concepts: commits and refs. With only these two concepts, and 
showing how high-level commands (remember: no plumbing) work with these 
concepts, I believe it is possible to teach anyone to use Git well. Of 
course, as users progress towards becoming power-users, more concepts are 
needed, but I don't think these are needed from the start.

As Einstein might have said: As simple as possible, but no simpler.


Have fun!

...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net