From: Johan Herland <johan@herland.net>
Date: Thu, 29 Nov 2007 08:24:12 GMT
Subject: Re: What's cooking in git.git (topics)
Message-ID: <200711290924.12508.johan@herland.net>
In-Reply-To: <7vlk8hzx0g.fsf@gitster.siamese.dyndns.org>

On Thursday 29 November 2007, Junio C Hamano wrote:
> Nicolas Pitre <nico@cam.org> 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, <johan@herland.net>
www.herland.net