Subject: Re: What's cooking in git.git (topics)

From: Johan Herland <[email-masked]>
Date: Thu, 29 Nov 2007 09:24:12 +0100

On Thursday 29 November 2007, Junio C Hamano wrote:
> Nicolas Pitre <[email-masked]> writes:
> > ...  In all the tutorials for $job I've done so 
> > far, I simply never talk about pull nor clone, but rather about init, 
> > "git remote", fetch and merge, with explicit and meaningful branch 
> > names.  I think that basic commands, even if there is a bit more of 
> > them, make Git easier to learn and understand than talking about those 
> > magic meta commands hiding the truth away.
> 
> That's actually a quite interesting approach for teaching.
> 
> The original "tutorial" (now core-tutorial) was similar in spirit; it
> built the user experience by starting at sequence of low level commands,
> and then finally said "since this is so often used combination, there is
> a short-hand for it that does all".  I think the approach would work
> quite well for people who want to use the tool with deep understanding.
> 
> However, I am not so sure about people who just want canned set of
> instructions and follow them blindly to get their work done.  And I do
> not think the latter classes of users are necessarily wrong.
> 
> Such a canned set of instructions would (if the project that supplies
> the cheat-sheet encourages merges instead of rebases) talk about "clone
> then commit then push then pull and repeat", without mentioning what
> pull does is fetch+merge nor what fetch means and what merge means, and
> that would let people get started without deeper understanding.
> 
> But the lack of deeper understanding would hurt them in the longer run
> (e.g. "my push was rejected with something called non-fast-forward ---
> what does that mean and what would I do now?").  

What about ending the cheat-sheet with a big fat link to a FAQ? The FAQ 
answers common questions like the above (resulting from the cheat-sheet 
glossing over the details) with links to appropriate sections in the more 
thorough introduction (core-tutorial), explaining what's _really_ going on.

Just a thought.

Have fun! :)

...Johan

-- 
Johan Herland, <[email-masked]>
www.herland.net