documentation feature request: don't alphabetize subcommands

[frederik at ofb.net]

Dear Mercurial People,

I don't use Mercurial or know much about it. Every once in a while I
think to myself "I should learn about Mercurial", and I start reading
the man page and scroll down until I see "add" ... "addremove" ...
"annotate" ... "archive" ... and then I give up...

I realize that alphabetizing stuff has a venerable pedigree: the
cvs(1) man page alphabetizes subcommands, and even global flags. For
me it just doesn't make sense - we read the documentation on digital
devices, and when we want to find a particular word we use a search
feature, rather than bisecting the alphabet. It would be kinder to new
users, without which no project could survive, to put things in a
sensible order for learning purposes. I feel it is unfortunate that
many projects list concepts in alphabetical order. This has the
appearance of being organized but really is just uninformative.

I realize that many people learn first from tutorials rather than
manual pages. I feel that even when tutorials are available, it is
still helpful to have a canonical reference document, which should be
sensibly organized, to which one can refer while following the
tutorial, and which is useful for further study afterwards.

By the way, I've been trying to work with the Git maintainers to
de-alphabetize the subcommand listing in the git(1) manual page. They
didn't want to do it themselves; so I ended up skimming all 150+
subcommand pages and coming up with an ordering of my own, and sending
a patch. Now the patch seems to be languishing... I mention this in
case someone has the idea of asking me to do the same thing for
Mercurial. I'm not offering to do that; I'm just offering my
perspective as a prospective user.

I'm not subscribed to the mailing list, so please Cc me if you have
any questions.

Thank you,

Frederick