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:
Are there other criteria/options I should consider for determining optimal order when user clarity / ease-of-use is the goal?
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.
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.