On Thu, 30 Nov 2006 18:44:41 -0800 (PST), Linus Torvalds wrote: > 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: > 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. > 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. > 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). > 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". ... > - use "git commit -a" normally (with pointers on fancier usage) ... > - 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. > - 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"). > 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
Attachment:
pgpTGJT0CatOX.pgp
Description: PGP signature