{"thread":{"id":"43440","subject":"Re: multi-project repos (was Re: Cleaning up git user-interface","startedAt":"2006-11-17T05:11:57Z","lastAt":"2006-11-17T10:02:02Z","messageCount":3,"participants":["Johannes Schindelin","Sean","linux@horizon.com"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"296227","messageId":"20061117051157.27896.qmail@science.horizon.com","threadId":"43440","inReplyTo":null,"subject":"Re: multi-project repos (was Re: Cleaning up git user-interface","fromName":"","fromEmail":"linux@horizon.com","sentAt":"2006-11-17T05:11:57Z","receivedAt":"2006-11-17T05:11:57Z","isPatch":false,"sender":{"key":"linux@horizon.com","avatar":null},"body":">> A lot of the complaints seem to not be about the interfaces, but about \n>> people not _understanding_ and knowing what the interfaces do. If you were \n\n> From the point of view of a user, there is not really a difference\n> between the two.  As a user, you form a mental model of how things\n> work by looking at the interface.  If the interface is bad, the user\n> creates a faulty model in his head, and starts doing things that\n> are perfectly logical in the faulty model, but stupid and silly when\n> you consider the actual internals.\n\n\"The only intuitive user interface is the nipple; all else is learned.\"\n\nAs Linus is explaining, the fundamental *problem* is the mental model.\nOnce you know how to break your goals apart into the right kind of pieces,\nlittle things like terminology are truly little.\n\nI'm not sure that git is sufficiently like anything else that a few\nwell-chosen command names can bring a good analogy to mind.  There just\nisn't a simple analogy that won't lead you astray; you have to understand\nthe thing on its own terms.\n\nHow do you explain the point of an electric screwdriver to someone who's\nnever seen a screw?  He'll think it's a silly way to wind up yarn.\n\n\nI'll be the first to explain that the git docs have some major problems.\n\"git show\" is a really useful command.  It has a zillion options to do\ncool things.  Have you read the man page?\n\nDidn't take long, did it?  \"git log\" is even more powerful, and almost\nas bad.  The information is all available, it's just on the plumbing\nman pages.\n\nAnd I even understand *why* it's there.  Because writing the plumbing is\nwhen the coders were thinking about the problem.  And writing good docs\nis very simple: when you learn something, write it down.  Not later,\nor next week, but right now, when you still remember how confused you\nwere before and what led you to the revelation.\n\nThe only problem, for a person looking at it top-down, is that git was\nwritten bottom-up, so the bottom is very well documented, and once you\nunderstand that, the top is pretty obvious and trivial.\n\nBut if you want to improve the situation for someone like yourself,\nthe solution is the same: when you learn something non-trivial, write\nit down.  Not later, after you've finished learning, but right now when\nyou still remember the process of learning.\n\nNow, when you show people what you wrote, one of two things will\nhappen:\n1) They'll say \"thank you, that's a good way of looking at it\", or\n2) They'll say, \"that's not quite right; the truth is actually...\".\n   The second case means that you have a bit more to learn.\n   But by taking the first step, you've given the learning process\n   some momentum.  It gets easier after that.\n\nI hope my recent postings ([DRAFT] Branching and merging with git)\nform a reasonable example of that.\n\n\nThere are a few key concepts in the git tools.  I don't care if\n\"git-rev-list\" is an ugly name; the name isn't learly as important as\nrealizing that *every* command that works on a list of commits uses\nthe same primitive, and what you learn about one command in that family\n"},{"id":"295612","messageId":"BAYC1-PASMTP0363A52FA4E6EE87232B20AEE80@CEZ.ICE","threadId":"43440","inReplyTo":"20061117051157.27896.qmail@science.horizon.com","subject":"Re: multi-project repos (was Re: Cleaning up git user-interface","fromName":"Sean","fromEmail":"seanlkml@sympatico.ca","sentAt":"2006-11-17T05:42:10Z","receivedAt":"2006-11-17T05:42:10Z","isPatch":false,"sender":{"key":"seanlkml@sympatico.ca","avatar":"https://gravatar.com/avatar/f92923f54fc08c401fc59b71829d4b89e9b8087fbba45ff87c82e6a83aee02ae?d=mp&s=160"},"body":"On 17 Nov 2006 00:11:57 -0500\nlinux@horizon.com wrote:\n\n> \"The only intuitive user interface is the nipple; all else is learned.\"\n\nThe thing is that other SCM's like hg look a lot more like a nipple than\nGit.  And they have the same conceptual models, more or less, to deal with\nas Git.\n\nSo why is it so many people think Git has a UI problem where the same\ncomplaint isn't levelled at Mercurial?  The thing is, the focus of\nGit has been different, it's been about creating great plumbing.  It's\nhad great success at doing that, and anyone who warms up to Git is well\nrewarded with a tool that gives them a lot of power and flexibility.\n\nBut Junio and others that have done most of the work have gone so far\nas to say Git is basically now feature complete.. the plumbing is more\nor less done.\n\nSo now it's time to make that plumbing more accessible and less\nintimidating to the uninitiated.  And blaming them for having the wrong\nmental model is just fundamentally the wrong approach.  No amount of\ndocumentation is going to replace having tools that are the least\nsurprising they can be and Just Work more often than not.  Other\nmodern SCM's have managed to do a better job of this than Git, and\nthere's no reason Git can't do better than it has.\n\nAs long as no damage is done to the underlying architecture and\nprinciples of Git there really shouldn't be _any harm_ in trying\nto do a better job of the porcelain layer.\n\n"},{"id":"294791","messageId":"Pine.LNX.4.63.0611171058190.13772@wbgn013.biozentrum.uni-wuerzburg.de","threadId":"43440","inReplyTo":"20061117051157.27896.qmail@science.horizon.com","subject":"Re: multi-project repos (was Re: Cleaning up git user-interface","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2006-11-17T10:02:02Z","receivedAt":"2006-11-17T10:02:02Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Fri, 17 Nov 2006, linux@horizon.com wrote:\n\n> How do you explain the point of an electric screwdriver to someone who's \n> never seen a screw?  He'll think it's a silly way to wind up yarn.\n\nI show him how to use it. And that's actually a fine analogy: While the \nprinciple of a screw is quite clever, working with it -- even with an \nelectric screwdriver -- is easy. And the most important part: I never read \ninstructions on how to use it. I saw somebody use it and -- voila! -- I \ncan use it myself.\n\n> I'll be the first to explain that the git docs have some major problems. \n> \"git show\" is a really useful command.  It has a zillion options to do \n> cool things.  Have you read the man page?\n\nI think that the importance of documentation is overrated. Users have come \nto expect to use programs without reading a manual. DWIM comes to mind.\n\nCiao,\n"}]}