Take the 2-minute tour ×
User Experience Stack Exchange is a question and answer site for user experience researchers and experts. It's 100% free, no registration required.

I'm thinking of providing two versions of help message for my command-line programs (cmd --help). The first one is the short version and the one users consult more often, mostly for examples and the list of options. It should not exceed one screen long so user does not need to scroll. It needs only to contain usage, usage examples, and list of options and a short one-line summary for each option (I am even thinking of not including any summary for each option, since they often make the help message too long already, if there are many options). Example:

Usage: 
  list-my-perl-dist-repos --help (or -h, -?)
  list-my-perl-dist-repos --version (or -v)
  list-my-perl-dist-repos [options]

Examples:
  list-my-perl-dist-repos --nodzil
  list-my-perl-dist-repos --detail --has-todo

Options: 
  --action=s 
  --debug 
    Set log level to debug and up. 
  --format=s 
    Choose output format, e.g. json, text. 
  --format-options=s 
    Pass options to formatter. 
  --log-level=s 
    Set log level. 
  --quiet 
    Set log level to quiet (error and up). 
  --trace 
    Set log level to trace and up. 
  --verbose 
    Set log level to verbose (info and up). 
  --detail [bool] 
    If true, show records instead of just names. 
  --dzil [bool] 
    Only include dists using dzil. 
  --exclude-path [str] 
    Exclude dists matching pattern. 
  --git-modified [bool] 
    Include dists which has modified files. 
  --git-untracked [bool] 
    Include dists which has files untracked by git. 
  --has-todo [bool] 
    Only include dists which have .todo-* flag files. 
  --include-pat [str] 
    Only include dists matching pattern. 
  --public [bool] 
    Only include public (CPAN) dists. 
  --noreleased [bool] 
    Only include released dists. 
  --sharyanto [bool] 
    Only include dzil dists using @SHARYANTO plugin bundle. 
  --task [bool] 
    Only include task dists. 

  For more verbose help, type ....

The second version are longer and contain longer description for the program as well as each options.

Usage: 
  list-my-perl-dist-repos --help (or -h, -?)
  list-my-perl-dist-repos --version (or -v)
  list-my-perl-dist-repos [options]

Examples:
  list-my-perl-dist-repos --nodzil
  list-my-perl-dist-repos --detail --has-todo

Description:
  This program lists perl distribution repositories located in ~/repos.
  Since there might be hundreds of repos on this directory, listing 
  and filtering them according to some criteria is useful.

Options: 
  --action=s 
    This option can be used if there is a default subcommand and
    you want to use a different subcommand.

  --debug 
    Set log level to debug and up.

  --format=s 
    Choose output format, e.g. json, text. 

  --format-options=s 
    Pass options to formatter. 

  --log-level=s 
    Set log level. 

  --quiet 
    Set log level to quiet (error and up). 

  --trace 
    Set log level to trace and up. 

  --verbose 
    Set log level to verbose (info and up). 

  --detail [bool] 
    If true, show records instead of just names. 

  --dzil [bool] 
    Only include dists using dzil. 

    Using dzil is determined by the existence of dist.ini file.

  --exclude-path [str] 
    Exclude dists matching pattern. 

  --git-modified [bool] 
    Include dists which has modified files. 

  --git-untracked [bool] 
    Include dists which has files untracked by git. 

  --has-todo [bool] 
    Only include dists which have .todo-* flag files. 

    The todo items (the part after the .todo-* filenames) are also
    listed.

  --include-pat [str] 
    Only include dists matching pattern. 

  --public [bool] 
    Only include public (CPAN) dists. 

    Private dists are marked by being named priv-perl-* instead
    of perl-*.

  --noreleased [bool] 
    Only include released dists. 

    A dist that has never been released is marked by the 
    presence of the .unreleased flag file.

  --sharyanto [bool] 
    Only include dzil dists using @SHARYANTO plugin bundle. 

    This is determined by parsing the dist.ini file.

  --task [bool] 
    Only include task dists. 

    This is determined by looking at the dist name (perl-Task-*).

My questions are:

  1. Do you think providing two version of help message a good idea? I admit this is rarely encountered in the wild: the main reason I'm planning to do this is because I'm getting annoyed with the length of the help message forcing me to scroll up.
  2. If this needs to be done, how would the interface go? I'm thinking of several alternatives:
    cmd --help --help,
    cmd --help -v (for "verbose help"),
    cmd --help --more,
    cmd --help=2,
    cmd --help=verbose.
share|improve this question
    
This appears to be off topic... This site isn't for coding. Use www.stackoverflow.com –  Majed Sep 24 '13 at 13:26
9  
@Majed it looks like a usability question to me. It's about usability of a command line app, but that's still usability. –  Racheet Sep 24 '13 at 15:28
    
@Racheet fair enough! –  Majed Sep 24 '13 at 15:53
1  
PowerShell does something similar to this - normal help is relatively brief; additional help is available with a couple of different levels of detail. For your situation, I'd suggest cmd /? or cmd -h for the summary and cmd --help for detailed. –  Bevan Sep 24 '13 at 21:56
    
@Bevan I personally think that's rather confusing, but thanks for pointing it out. –  Steven Haryanto Sep 25 '13 at 5:39
show 1 more comment

5 Answers 5

up vote 8 down vote accepted
  1. Yes, "mysqld --help --verbose" already exists to get more details on help.
  2. I would use "-- help --verbose" or "-help -verbose", this would at least be familiar to mysqld users
share|improve this answer
add comment

This might not be applicable in your case, but I've seen solutions where typing a command line command without parameters will bring up a short help or reference, and typing the command -help brings up the actual help.

For example see screenshots below, from the cli for yeoman:

Typing without parameters (yo) brings up (an interactive) help dialogue: enter image description here

And accessing the longer help entry (yo -help): enter image description here

Personally I really like this approach, because it is very intuitive and detects when the user does not know what to do (i.e. show the help when a needed parameter is not provided).

share|improve this answer
2  
Thanks, the approach is nice but not applicable when a program does not have subcommands (i.e. they should already do something even when invoked without any options). –  Steven Haryanto Sep 25 '13 at 5:45
    
Valid point indeed. –  kontur Sep 25 '13 at 16:51
add comment

In my experience -h -v would be a confusing way to spell this. (Or --help --verbose, which is the same thing written in longopts format.)

Three other ways:

  1. Some commands provide a quick summary of help if run without any options, with -h/--help providing longer help. If your command does something useful even without options, this might not work.
  2. Some commands (e.g. Perforce's p4, or git) show a summary of available help when run without options, pointing at more specific help (p4 commands, git help add).
  3. Some commands provide short help with -h / --help, and longer help with a different option like --man or --long-help or --help-long or -H. (Some even use -h for short help and --help for long help, but I find that confusing.)

Alternatively, you can use the extant man feature on *nix, and say, "for more detailed help, type man my-really-long-command-name.

share|improve this answer
1  
Thanks for the input. Not all programs use subcommands, so #1 is not applicable everywhere. As for programs that have subcommands, when run without any arguments I like them mostly to print the list of available (or popular) subcommands, so that's a rather different help message. –  Steven Haryanto Sep 25 '13 at 5:41
    
As for #3, what program is that? Thanks. –  Steven Haryanto Sep 25 '13 at 5:43
add comment

A Common Approach

The most common way of drilling-down to see less frequently used options or greater details in --help messages seems to be appending to '--help' as the following sample options illustrate...

command [--OPTION...]
    Does something useful in an intuitive way.
    Options:
        --quiet (-q)
            Execute command with no feedback.
        --verbose (-v)
            Execute command with detailed feedback.
        --help (-h)
            Show common options.
        --help-gtk
            Show GTK+ GUI options.
        --help-general
            Show description and syntax conventions.
        --help-details
            Show complete documentation for all options.
        --help-man
            Show manpage for this program.
        --help-info
            Show info page for this program.
        --help-online
            Show online help in default browser.
    Revised:
        20130928 docsalvage

Supplemental...

Here, --help shows "simple help", and --help-general (sometimes abbreviated --help-gen) would show the complete, detailed help.

As @kontur mentioned, entering the command alone would show basic --help.

The example above includes several common options for illustration purposes but rarely would a program warrant using all of them.

If an extensive overview or other general verbiage is desired, that might be shown by --help-general with the full documentation for each and every option handled separately by --help-details.

If a Linux manpage is created, something like --help-man might be used to call the command to show it.

man
The standard Linux command that shows the "manual page" (aka "manpage") for the command. Manpages are the standard help system available in all versions of Unix and Linux. Each page includes the full documentation for a command. Manpages use a special format and so are a bit involved to create. Thus often, no manpage is created for locally developed scripts and programs.

Likewise, there is a newer, more robust documentation system called "info" that supports hyperlinking and other features, that many new programs are using. It would be accessed by --help-info if the developer created an info page. The downside of info is that it can be cumbersome and unintuitive so it's not widely used.

What is more widely used, especially for large programs, is online help. Documentation can be easily improved without having to push out a new version. Using an option like --help-online would effectively be like clicking on a hyperlink. The default browser would be started if not already running and overlay the terminal window. The first page of the documentation would appear in a new tab.

share|improve this answer
    
How does this address simple help versus more detailed help? –  kontur Sep 28 '13 at 15:01
add comment

Provide only a single "version" of help. Put a short summary at the begining, and put the full details under it.

If the short version is enough, then no scrolling is required. If it is not enough your users don't have to go looking someplace else, they just scrol down to it.

share|improve this answer
3  
But the terminal will likely autoscroll so that the helpful summary will be off the top of the page. I'm not sure this is going to be an effective solution. –  Racheet Sep 24 '13 at 15:29
    
Maybe there is different type of scrolling behaviours for the terminal on different OS. On my OS X the terminal shows as much as it can fit, the rest you have to scroll down to by the down arrow. –  kontur Sep 25 '13 at 16:50
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.