Improve `--help` output #3

Open
DamonOehlman opened this Issue Jul 11, 2012 · 1 comment

Comments

Projects
None yet
2 participants
Owner

DamonOehlman commented Jul 11, 2012

Provision has been made within scaffolder to generate help as both a command listing, and also as specific help for particular commands.

Needs to be completed.

Zearin commented Sep 14, 2012

Recommendations for good help text generation

I noticed that you’re using ReST for your documentation, which suggests you’re familiar with Python.

If that’s the case, may I recommend modeling your efforts towards an experience like those seen in these Python modules:

  • cmd2 is a command-line framework that builds on the standard library’s cmd module, with built-in tab-completion and help for commands and command-options. Although it uses the outdated optparse module from the standard library, the user experience is good.
  • argparse is the successor to the older optparse module. It’s powerful, but a pain in the ass to use.
    • So someone built a human-friendly wrapper around it: argh.

Recommended guidelines for programmer-friendly help text

Node.js isn’t Python. But what I’m trying to say is, the more programmer-friendly a help-text generator is, the more user-friendly the CLI will be.

From this project’s README, I’m guessing that you share my frustration with command-line tools that have crappy help (or sometimes no help!). When the tools for writing command-line applications are good enough, this doesn’t happen.

I think the key ingredients for this are as follows:

  • Help text is taken from code that lives alongside the command (or option) it describes
  • Help text is formatted for readable output automatically; the programmer shouldn’t need to put indentation into help-text strings (99% of the time)
  • Help text is assembled automatically, but allows for flexibility via:
    • pre-text and post-text style callbacks (for printing intro/appendix paragraphs around the standard help text)
    • Optionally—“short” and “full” help. (Sometimes help is invoked for a complete reference, but sometimes the user just needs to jog their memory.)
    • Examples:
    • Github’s conventions for commit messages (a one-line overview, followed by optional longer description)
    • Python’s conventions for docstrings (similarly, a one- or two-sentence description, followed by a blank line and a longer description)
    • Invocation varies. Some use --help --verbose for full help; others offer a summary via --usage and full help via --help.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment