Re: multi-project repos (was Re: Cleaning up git user-interface

Re: multi-project repos (was Re: Cleaning up git user-interface

[linux]

>> A lot of the complaints seem to not be about the interfaces, but about 
>> people not _understanding_ and knowing what the interfaces do. If you were 

> From the point of view of a user, there is not really a difference
> between the two.  As a user, you form a mental model of how things
> work by looking at the interface.  If the interface is bad, the user
> creates a faulty model in his head, and starts doing things that
> are perfectly logical in the faulty model, but stupid and silly when
> you consider the actual internals.

"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 case means that you have a bit more to learn.
   But by taking the first step, you've given the learning process
   some momentum.  It gets easier after that.

I hope my recent postings ([DRAFT] Branching and merging with git)
form a reasonable example of that.


There are a few key concepts in the git tools.  I don't care if
"git-rev-list" is an ugly name; the name isn't learly as important as
realizing that *every* command that works on a list of commits uses
the same primitive, and what you learn about one command in that family

Re: multi-project repos (was Re: Cleaning up git user-interface

[Sean]

On 17 Nov 2006 00:11:57 -0500
linux@horizon.com wrote:

> "The only intuitive user interface is the nipple; all else is learned."

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.

Re: multi-project repos (was Re: Cleaning up git user-interface

[Johannes Schindelin]

Hi,

On Fri, 17 Nov 2006, linux@horizon.com wrote:

> 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 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 
can use it myself.

> 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?

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,