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

[Stephen J. Turnbull]

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'm waiting for bzr to grow full-service MUA features and become
Emacs....

 > 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.

Can't this complex structure be simplified?  Well, remember that that
was the reason for Info in the GNU Project, and that failed (cf
Debian's "this man page was written for the Debian Project" man
pages).  There's a reason for this complexity in the documentation: it
reflects complexity in the application.  Today bazaar is a very
complex application.  I see no reason why bazaar's complexity should
not be reflected in the structure of its documentation.

In this particular case, there's an obvious simplification, which John
already suggested: one major source of complexity is log formats.
Separate it into a "log formats" help topic, referenced from bzr help
log.  People who need to know more than their names will welcome a
verbose, multipage discussion.  (N.B. This is already done for revisions,
with the revisionspec help topic.)  That would go a long way to
reducing the size of bzr help log to one page.  Don't be misled by the
fact that log formats are unique to the log command.  It's not how bzr
uses log formats that should determine the structure of the
documentation; it's how users want to use "bzr help" that should do so.

 > 2. Following DRY, our User Reference is built from the online help
 >    so that the two are always in sync.

This is a good principle, one you should maintain.  But it should be
possible to arrange that the same documentation sources produce brief
usage reminders, formal user reference material, and perhaps
background/theory of operation/etc, depending on context or options.

 > FWIW, my enhanced log help is 3-4 pages in length. *I* don't
 > think that's excessive when compared to other tools:

Don't bother about that.  The other VCSes have their users and their
styles.  bazaar's style is (and should be!) different.

 > So, I'd like to propose that:
 > 
 > * We continue to keep the User Reference and online help
 >   in sync

+1

 > * "bzr help xxx" and "bzr xxx -h" give comprehensive help

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.

If the user needs more than the brief help, then they can amortize the
extra invocation of "bzr help --comprehensive" over the relatively
long time they were going to spend studying the help anyway.

 > * "bzr help -?" be supported & it should show just the one line
 >   summary and list the options.

Why not "bzr help -+"?<duck />  Seriously, the fact that you see a
need for a very terse and unintelligible option shows that this should
be the default behavior.