Re: de-alphabetizing the documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 13, 2018, 18:17 UTC
Message-ID: <xmqqva8e5dxj.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <20180811023036.GA19208@ofb.net>

frederik@ofb.net writes:

Show 11 quoted lines

> 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 ;-).