Re: de-alphabetizing the documentation

[Junio C Hamano <gitster@pobox.com>]

frederik@ofb.net writes:

> Hi Jonathan and Git developers,
>
> I poked around today and figured out how to reorder the command
> listings in the manual page, they are taken from git/command-list.txt
> so I just reorder the lines in that file (after disabling sorting in
> git/Documentation/cmd-list.perl).
>
> I haven't reordered the whole list yet. I could only get one computer
> friend to send me his subcommand frequencies from his shell history. I
> reordered the commands partly based on that, and partly based on their
> order of occurrence in the various tutorial man pages.

There are two good things about a list that is alphabetical.  One is
that you can scan with your eyes and a finger to find what you are
looking for more quickly.  The other is that it is mechanical so we
won't waste time on bickering whose frequency table is more correct,
whether frequency table is a good approach to derive a better order
(than, say, the order in which the commands appear in an every-day
workflow) to begin with.

I would say if we were departing from alphabetical order, we should
first declare that we are *not* looking for the best way to order
the list, so that people do not waste too much time bikeshedding.
Instead what we should aim for is to come up with _an_ order that is
not too unreasonable and settle as quickly as we can.

And from that point of view, what I saw in new-git.1.out, I found it
not so outrageously unreasonable ;-).