"The only intuitive user interface is the nipple; all else is learned."
As Linus is explaining, the fundamental *problem* is the mental model.

Once you know how to break your goals apart into the right kind of pieces,

little things like terminology are truly little.
I'm not sure that git is sufficiently like anything else that a few

well-chosen command names can bring a good analogy to mind.  There just

isn't a simple analogy that won't lead you astray; you have to understand

the thing on its own terms.
How do you explain the point of an electric screwdriver to someone who's

never seen a screw?  He'll think it's a silly way to wind up yarn.
I'll be the first to explain that the git docs have some major problems.

"git show" is a really useful command.  It has a zillion options to do

cool things.  Have you read the man page?
Didn't take long, did it?  "git log" is even more powerful, and almost

as bad.  The information is all available, it's just on the plumbing

man pages.
And I even understand *why* it's there.  Because writing the plumbing is

when the coders were thinking about the problem.  And writing good docs

is very simple: when you learn something, write it down.  Not later,

or next week, but right now, when you still remember how confused you

were before and what led you to the revelation.
The only problem, for a person looking at it top-down, is that git was

written bottom-up, so the bottom is very well documented, and once you

understand that, the top is pretty obvious and trivial.
But if you want to improve the situation for someone like yourself,

the solution is the same: when you learn something non-trivial, write

it down.  Not later, after you've finished learning, but right now when

you still remember the process of learning.
Now, when you show people what you wrote, one of two things will

happen:

1) They'll say "thank you, that's a good way of looking at it", or

2) They'll say, "that's not quite right; the truth is actually...".

   The second ca...
[ message continues ]

Hi,
I show him how to use it. And that's actually a fine analogy: While the

principle of a screw is quite clever, working with it -- even with an

electric screwdriver -- is easy. And the most important part: I never read

instructions on how to use it. I saw somebody use it and -- voila! -- I 
I think that the importance of documentation is overrated. Users have come

to expect to use programs without reading a manual. DWIM comes to mind.
Ciao,

Dscho

-

On 17 Nov 2006 00:11:57 -0500
The thing is that other SCM's like hg look a lot more like a nipple than

Git.  And they have the same conceptual models, more or less, to deal with

as Git.
So why is it so many people think Git has a UI problem where the same

complaint isn't levelled at Mercurial?  The thing is, the focus of

Git has been different, it's been about creating great plumbing.  It's

had great success at doing that, and anyone who warms up to Git is well

rewarded with a tool that gives them a lot of power and flexibility.
But Junio and others that have done most of the work have gone so far

as to say Git is basically now feature complete.. the plumbing is more

or less done.
So now it's time to make that plumbing more accessible and less

intimidating to the uninitiated.  And blaming them for having the wrong

mental model is just fundamentally the wrong approach.  No amount of

documentation is going to replace having tools that are the least

surprising they can be and Just Work more often than not.  Other

modern SCM's have managed to do a better job of this than Git, and

there's no reason Git can't do better than it has.
As long as no damage is done to the underlying architecture and

principles of Git there really shouldn't be _any harm_ in trying

to do a better job of the porcelain layer.
Sean

-