On Thu, 30 Nov 2006, Joseph Wakeling wrote: > > What would be nice would be to have in the documentation a whole bunch > of stupid examples for the main commands, something where someone can > create a repo from scratch, create and modify some simple files > according to instructions, and see the particular command in action. 100% agreed. A lot of the man-pages etc have been written to be about the technology, not about the _use_ of it. I encouraged people at some point to add an "Examples" section to some of the functions to show what it all _means_, so for "man git-log", I think some of the most useful stuff is that examples section that shows the combination of revision naming and path-name limiting, for example. I personally think that that is a much better way of teaching people what the commands actually do than by mentioning the arguments one by one. But that only exists for a couple of man-pages, and mostly for the simple ones at that. And a lot of the real examples would need "real data" to work on, so it can't easily be done as a trivial example in a man-page, it really needs a tutorial to "build up" to the situation where you can then explain with an example what to do. > The tutorials do this, of course, but only for a few cases, when to be > honest it's the more complex commands that most need such explanation. Yeah. The git "tutorial.txt" should be extended, and preferably be a while nice set of "follow along with the bouncing ball" kind of web-page sequence. So I absolutely agree. It's just that at least me personally, I just can't write documentation. I wrote some of the original tutorial, I've written some of the original tech docs, but I just can't get into the whole "document it" mindset, especially not from a user perspective. It doesn't float my boat, and judging by a lot of the discussions, I obviously also don't even see why something could _possibly_ cause confusion. To make things worse, a lot of the docs (and by that I also mean some of the error messages and helpful hints) tend to be old. The whole fact that "git commit" mentions "git update-index" is exactly that kind of thing: it's largely a legacy message. You'd almost never actually _use_ git-update-index itself these days, and it's much more convenient to just list the files you want to commit to "git commit" directly (or just use the -a flag, if that is what you want to do). But that message exists, because it was written in an earlier age. Linus - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html