On Thu, 30 Nov 2006 18:44:41 -0800 (PST), Linus Torvalds wrote:
quoted text
> I really think we're better off just telling people how things work (with
> practical examples, and _not_ by trying to explain things at too high a
> conceptual level).
>
> I don't think people generally are all that stupid, and I think it's
> actually counter-productive to try to basically lie about how things work.
> It will just make it harder for people later.

Sure. There's no need to lie to about how things work. And I agree
that would cause later problems. As far as getting the message out, we
have several different ways to do that:

  1. In-person presentations, demos, tutorials

  2. Written tutorials

  3. Reference documentation

  4. Output from git commands

  5. The default behavior of git commands

And that list is roughly sorted from most to least "information
bandwidth". The limited bandwidth at the bottom-most levels in my
list, (together with the fact that people often start trying the tool
at only those levels), means we have to be even that much more careful
about the messaging there.

In my experience, I think we succeed quite well at level 1. In person,
we get immediate feedback from the user and it's easy to catch and
cut-off any user confusion up-front. "Oh, you don't even need to run
that command...use this instead", etc.

As for the other levels, you hit on most of them in your comments:

quoted text
> I really _think_ that a lot of that is in the documentation being overly
> technically oriented and talking often about the technical side of how
> things work in the index, rather than the purely user side of what that
> _results_ in.

Yes, this is a big problem at level 3. Things like the "man git-diff"
scare factor that Ted pointed out. So let's work to fix all of that.

quoted text
> I really believe that people can understand the concept of "git add"
> squirrelling away the whole state of the file at add-time, and suddenly
> it's not all that complicated. Also, it's not even something that people
> really need to worry about, and I think we should make that more clear.

One trick with saying "we just need to document this better" to avoid
the confusion is that approach assumes that the users are actually
_reading_ the right documentation. Now, we're currently making this
harder than it should be at level 4 by doing things like sending users
to the documentation for update-index. But still, if we can make
things less surprising in some cases _without_ needing the
documentation, then we make it that much easier.

quoted text
> In other words, the documentation could _literally_ give the example of
>
> 	git add file.c
> 	.. change file.c ..
> 	git commit
> 	git diff file.c
>
> and talk about this issue up-front,

Yes, adding lots of good examples to the written documentation will
help, (anyone that reads it at least).

quoted text
> that "if you don't want to know about these details, you can always just
> use 'git commit -a', and you'll never really even notice".
...
quoted text
>  - use "git commit -a" normally (with pointers on fancier usage)
...
quoted text
>  - and yes, we obviously should change the message to say "git commit -a"
>    instead of "git update-index"

So here you're arguing for documenting the heck out of "commit -a" at
all of levels 1-4. If we're going to do that, why not just go the next
tiny step and make it work as "git commit" by default, (which people
_will_ try). If we can say, "come from hg or bzr and things will just
work", people can try that, be satisfied that git isn't bizarre, and
then we can teach where git's actually superior.

quoted text
>  - do NOT use the "-m" flag, and look at what git tells you in the
>    commit message!

Interesting. I do use -m almost exclusively. I do that for speed I
think, (but I do do multi-line commit messages). The only drawback I
was aware of was that I'm doing manual word wrapping, but I might
start trying this to see information in the commit message, (instead
I've been checking first with "git diff --cached").

quoted text
> Ok, with that rant out of the way, my _point_ is that we're actually much
> better off educating users about _why_ git is different, than trying to
> lie to them and say "it's just like CVS by default, but when you're a real
> man, we'll show you how you can rock your world".

I still don't see any lie here. If we all agree that "git commit -a"
is the most commonly desired form, it's what users expect by default
(based on _any_ other system they might be coming from), and we agree
we need to mention it a lot more at every level of the
documentation---given all that, why do we insist on having something
else be the default?

Because it gives us an opportunity to teach about the power of the
index to anyone that gets confused and complains? That strategy
ignores everyone that gets confused and just leaves without talking to
us.

I'm talking about changing the default of what "git commit" does, yes,
but it can still be documented honestly as to what it really does and
why. It would fit in just fine with Nico's new documentation for "git
add" for example, and "git diff" doesn't need to be changed at all,
(but it's documentation should be made much less scary).

-Carl