[jcranmer]

> I don't find `man git` to be bad at all. Git is complex, and its man pages do the right thing by referring to sources for basics info like giteveryday, and referring to in-depth guides as well. Individual man pages are also pretty good, see `man git-rebase`. It starts with an overall explanation of what rebase does, with examples, and then covers configuration options and flags. It's a lot of stuff, but it's pretty good as far as documentation goes.

Having used both Mercurial and git, it is my general experience that Mercurial has a much better documentation system. Git's documentation has improved, but mostly only in the more-well-used commands; when you want to reach for more exotic stuff, you start to find that the documentation is too full of jargon.

As a recent example, I wanted to get a list of files managed by git. Since I know mercurial best, I wanted the equivalent of hg manifest. Its documentation is thus:

> hg manifest [-r REV]

> output the current or given revision of the project manifest

> Print a list of version controlled files for the given revision. If no revision is given, the first parent of the working directory is used, or the null revision if no revision is checked out.

This is unusually bad documentation for mercurial--the short description and command name are reliant on jargon, and it's not aliased to "hg ls" or something like that. Okay, how about the equivalent git command? git ls-files looks promising. Here's its short description:

> git-ls-files - Show information about files in the index and the working tree

But its description is, um:

> This merges the file listing in the directory cache index with the actual working directory list, and shows different combinations of the two.

Mercurial suffers from a bit of jargon, but reading its description would enlighten you as to what it does without understanding the jargon. Git's documentation here starts with jargon, and then doubles down on it so that the more I read, the less sure I am about what it actually does. [In the end, by actually running it, I did verify that it's basically the equivalent of hg manifest].

Now both mercurial and git have a glossary (help glossary), but I've never seen anyone actually point a newbie to either one. Of course, here you can also see the world of difference in the documentation quality. Mercurial's glossary entry for the jargon term "manifest" says:

> Each changeset has a manifest, which is the list of files that are tracked by the changeset.

Now compare git's glossary entry for "index":

> A collection of files with stat information, whose contents are stored as objects. The index is a stored version of your working tree. Truth be told, it can also contain a second, and even a third version of a working tree, which are used when merging.

... and that is why people like me say that git suffers from poor documentation.

[SAI_Peregrinus]

Git's documentation tends to tell you how it does what it does, without telling you what it's trying to accomplish. It's the equivalent of the classic beginner comment:

a += 5; // Add 5 to a

Entirely accurate, and totally useless.