CLI: How should I order sub-commands in usage messages?

Question

I'm developing a tool with a command line interface. I am seeking the clearest, most obvious/user-friendly way of ordering the sub-commands in the usage/error messages.

The nature of the tool is that some commands act purely locally, and some commands require network activities. Here are the various ways I can think of ordering or grouping the commands:

1. alphabetical: makes sense perhaps if the user already knows the name of the commands, but I instinctively don't like this
2. progressive: my term for the listing commands in the same order in which the user is likely to encounter them as they get to know the tool
3. progressive, but grouped by (non-)network use: that is, similar order to progressive, but grouping by network related commands (import, export, push, sync) and non-network related commands (the rest).

Are there other criteria/options I should consider for determining optimal order when user clarity / ease-of-use is the goal?

Answer 1

I would go with alphabetical ordering, even if I instinctively disliked it. When considering ease of use, think of the experience for a beginning user and an advanced user. A beginning user may not know what the name of a command is that they are looking for, so they'll just scan the list anyway, no matter the order. Alphabetical ordering won't slow down the advanced user, and may even speed up scanning if they already know the command name. You can research Hick's Law for more information on accessing information in lists.

Also, alphabetizing is a convention used elsewhere, at least in the Windows 7 command line that I checked in. I assume it's the same in Unix, without a command line in front of me, based on this online man page). Breaking a convention is usually not a good idea, unless there are guaranteed advantages to be had by breaking it.

Answer 2

The Gnits Standards for Command Line Interfaces offer the following advice, which seems similar to your third suggestion:

When a program has many options, try regrouping options logically, instead of listing them all alphabetically (say), as the mere regrouping is a succint way to convey much information. Present each group of options in its own subtable, suitably introduced by some few words. Separate groups by white lines for making the overall structure more easy to grasp by the reader. Here is an excerpt from a relatively big `--help' output:

Main operation mode:
  -t, --list              list the contents of an archive
  -x, --extract, --get    extract files from an archive
  -c, --create            create a new archive
  -d, --diff, --compare   find differences between archive and file system
  -r, --append            append files to the end of an archive
  -u, --update            only append files newer than copy in archive
  -A, --catenate          append tar files to an archive
      --concatenate       same as -A
      --delete            delete from the archive (not on mag tapes!)

Device blocking:
  -b, --blocking-factor=BLOCKS   BLOCKS x 512 bytes per record
      --record-size=SIZE         SIZE bytes per record, multiple of 512
  -i, --ignore-zeros             ignore zeroed blocks in archive (means EOF)
  -B, --read-full-records        reblock as we read (for 4.2BSD pipes)

Copyright (C) 1996 Free Software Foundation, Inc.