Re: Considering teaching plumbing to users harmful

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Jul 16, 2008, 23:19 UTC
Message-ID: <alpine.DEB.1.00.0807170105280.4318@eeepc-johanness>
In-Reply-To: <20080716214849.GF2925@dpotapov.dyndns.org>

Hi,

On Thu, 17 Jul 2008, Dmitry Potapov wrote:

Show 12 quoted lines

> On Wed, Jul 16, 2008 at 06:21:02PM +0100, Johannes Schindelin wrote:
> > 
> > I had the pleasure of introducing Git to a few users in the last 
> > months and in my opinion, restricting myself to teaching them these 
> > commands first helped tremendously:
> > 
> > - clone, pull, status, add, commit, push, log
> 
> Yes, it is a good list, and I think it is very important at the 
> beginning to limit the number commands to 7-8, otherwise many users may 
> be confused. And, of course, it is better to stay away from all 
> command-line options at first...

Thanks.

Show 7 quoted lines

> > All of these were presented without options, to keep things simple.
> > 
> > In particular, I refrained from giving them the "-a" option to commit.  
> > That seemed to help incredibly with their embracing the index as a 
> > natural concept (which it is).
> 
> Most things that we call as "natural" is those that we got used.

In this case, I have to add that it is natural because it is the way you _have_ to do it. Even if the other SCMs hide it.

You almost never commit a full revision. You usually update just a couple of files. Now, even CVS has an extra command to add a file, so it accepts the fact that staging and committing are two different operations, even if "cvs add" does not stage the changes of a tracked file.

Of course, it is easier for us: we can use all the lessons learnt from CVS.

Show 6 quoted lines

> > Now, it makes me really, really sad that Git has a reputation of being 
> > complicated, but I regularly hear from _my_ users that they do not 
> > understand how that came about.
> 
> I think this reputation is largely due to people who open Git user
> manual, read about >100 commands, were horrified and stopped learning.

Heh. I catually would be delighted if one outcome of this discussion would be that the user manual starts with a nice big chapter describing just my first set of commands, without options.

Another nice outcome could be if all the plumbing man pages were moved into a different section, and all the porcelain's man pages would be changed to avoid referring to plumbing.

It could be a good idea, too, to explain advanced topics not by command, but by scenario.

Show 6 quoted lines

> > Am I the only one who deems teaching plumbing to users ("I like it 
> > raw!  So I teach it the same way!") harmful?
> 
> There is only one thing that seems to be true about teaching Git (or
> anything else) -- there is no single method that works equally well
> for anyone.

I disagree.  I think that the first steps are the same for everyone.

Ciao, Dscho