Re: Considering teaching plumbing to users harmful

Hi,

On Wed, 16 Jul 2008, Theodore Tso wrote:

I've already said I agree with you, but maybe it would be helpful if you 
focused the discussion a little more with a concrete suggestion about 
how we could improve the user-visible documentation.

Well, I was not sure if I was full of shot or not.

So a concrete suggestion might be to move the list of plumbing commands 
from the top-level git man page to a "git-plumbing" man page.

I think that would not help much.

As I replied to Dimitry, I could imagine that moving the plumbing into its 
own manual section would be a way.

I'll note that the git user manual is pretty good about avoiding the use 
of git plumbing commands.  It's not until Chapter 9, "Low Level Git 
Commands" that it start going into the plumbing.  (There are a couple of 
mentions of git rev-parse before chapter 9, but that's about it that I 
could find).

Well, rev-parse is one of my pet peeves this day.  rev-parse is _nothing_ 
but plumbing.

Was there other git documentation where you think there is too many 
references to git plumbing?

Actually, the problem arose with a few "tutorials" on the web, and their 
creators violently arguing for their ways (and me being more and more 
uncertain if they are wrong or me).

And then I saw people on IRC doing the same thing.  Realizing that the 
recipients of the "help" were more confused than before, and just typed 
what was written (they would probably even have typed "rm -rf $HOME") 
because they had given up trying to understand.

Ciao,
Dscho