[RFC] Concise vs comprehensive help - do we need both?

[Ben Finney]

"Stephen J. Turnbull" <stephen at xemacs.org> writes:

> Ian Clatworthy writes:
>  > It sounds like there are competing needs w.r.t. our on-line
>  > help system:
>  > 
>  > 1. I expect help to be comprehensive, particularly for
>  >    key commands like branch, commit, log, merge and send.

I expect *documentation* to be comprehensive for all this. But I
expect just as much that ‘foocommand --help’ (or the equivalent) will
not be anywhere near that verbose.

>  > 1. We need to do a better job explaining what Bazaar can do
>  >    and in the case of commands at least, what better place
>  >    is there than the help for that command?
> 
> In the Unix tradition, there is no "the help". At a bare minimum,
> there is the *usage*, and there is the *man page*. In a large (?!)
> application such as bzr, there will also be a *user guide*. There
> may be other documents as well.
> […]

> The default should be short help. Even fairly new users will often
> be looking for something very simple ("I know there's a 'verbose'
> log format, but it's not 'verbose' and it's not 'full'..."). Having
> to wade through several pages to find the single word you need is
> enough to break your train of thought.

+1 to all this, and Stephen's message in general.

-- 
 \           “Man cannot be uplifted; he must be seduced into virtue.” |
  `\                                      —Donald Robert Perry Marquis |
_o__)                                                                  |
Ben Finney